# Public Cloud › Compute › Instances API

> Part of the OVHcloud developer hub. Index of every page and section: https://developers.eu.ovhcloud.com/llms.txt
> The Public Cloud product's sections: https://developers.eu.ovhcloud.com/reference/public-cloud/llms.txt
> Everything in one file: https://developers.eu.ovhcloud.com/llms-full.txt

> 7 operations of the OVHcloud API. Calls carry `authorization: Bearer $OVH_TOKEN`; the EU host is shown, Canada and the United States answer on api.ca.ovhcloud.com and api.us.ovhcloud.com.

Page: https://developers.eu.ovhcloud.com/reference/public-cloud/compute/instances/

OpenAPI v1: https://api.eu.ovhcloud.com/1.0/__schemas/developer-hub-navigation/public-cloud/compute/instances.json?format=openapi3
OpenAPI v2: https://api.eu.ovhcloud.com/v2/__schemas/developer-hub-navigation/public-cloud/compute/instances.json?format=openapi3

## Operations

- `GET /publicCloud/project/{projectId}/compute/instance` — List instances
- `GET /publicCloud/project/{projectId}/compute/instance/{instanceId}` — Get an instance
- `GET /publicCloud/project/{projectId}/compute/instance/{instanceId}/compatibleFlavor` — List compatible flavors
- `POST /publicCloud/project/{projectId}/compute/instance` — Create an instance
- `POST /publicCloud/project/{projectId}/compute/instance/{instanceId}/action` — Run an instance action
- `DELETE /publicCloud/project/{projectId}/compute/instance/{instanceId}` — Delete an instance
- `PUT /publicCloud/project/{projectId}/compute/instance/{instanceId}` — Update an instance

## List instances

`GET /v2/publicCloud/project/{projectId}/compute/instance`

Link: https://developers.eu.ovhcloud.com/reference/public-cloud/compute/instances/#getInstances

**Status:** Stable production version  
**IAM actions:** `publicCloudProject:apiovh:instance/get`

### List instances

Lists all instances in the project. Each item is a full instance envelope with the same shape as the `GET` route (desired `targetSpec` and observed `currentState`).

### Filesystem attachments
For performance, `currentState.shares` is not populated in list responses. To see the filesystems attached to a given instance, call `GET .../instance/{instanceId}` on it.

### Filters
The optional `name`, `flavor`, `region` and `status` query parameters narrow the list. Each one can be repeated, for example `?status=READY&status=CREATING`: repeated values of the same parameter are combined with OR, and different parameters are combined with AND. Filters apply only within the instances you are authorized to list. An unknown `status` value or an unavailable `region` is rejected with a `400 InvalidParameter`.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `X-Pagination-Cursor` | header | string |  | Pagination cursor |
| `X-Pagination-Size` | header | integer |  | Pagination size |
| `flavor` | query | string[] |  | Filter by flavor ID or flavor name. Repeatable. |
| `name` | query | string[] |  | Filter by instance name (case-insensitive substring match). Repeatable. |
| `projectId` | path | string | yes | Project ID |
| `region` | query | string[] |  | Filter by instance region. An unavailable region is rejected. Repeatable. |
| `status` | query | common.ResourceStatusEnum[] |  | Filter by resourceStatus. Repeatable. |

### Responses

| Status | Type | Description |
| --- | --- | --- |
| 200 | publicCloud.instance.Instance[] | successful operation |
| 400 | object | Error 400 response |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `checksum` | string | read-only | Computed hash representing the current targetSpec value. It enables optional optimistic concurrency control: the value returned by a GET may be sent back in the PUT and action payloads, and the request is then rejected with a 409 checksum-mismatch conflict if it no longer matches server-side (because another request modified the instance in the meantime). Sending no checksum skips that check and forces the write (last-write-wins). |
| `createdAt` | string (date-time) | read-only | Creation date of the instance, as an ISO 8601 / RFC 3339 timestamp |
| `currentState` | publicCloud.instance.InstanceCurrentState | read-only | Current observed state of the instance as reported by the compute backend (name, flavor, image, location, power state, networks, attached volumes, attached shares, security groups). It is null while the instance is still being created and no backend state is available yet. |
| `currentState.availableActions` | publicCloud.instance.InstanceAvailableAction[] | read-only | Availability of every instance action type given the current state of the instance. Always contains exactly one entry per InstanceActionTypeEnum value, in the order of that enum, each flagged with whether it can currently be triggered through the action endpoint. For example, when the instance is locked only UNLOCK is available. While a task is in progress on the instance or when it is in error, none is available. |
| `currentState.availableActions[].available` | boolean | read-only | Whether the action can currently be triggered through the action endpoint. A call with an unavailable action is refused. |
| `currentState.availableActions[].name` | publicCloud.instance.InstanceActionTypeEnum | read-only | Action type, as accepted by the action endpoint — one of `LOCK`, `PAUSE`, `REBOOT`, `RESCUE`, `RESUME`, `SHELVE`, `START`, `STOP`, `SUSPEND`, `UNLOCK`, `UNPAUSE`, `UNRESCUE`, … |
| `currentState.flavor` | publicCloud.instance.InstanceFlavor | read-only | Observed flavor of the instance with full details (name, vCPUs, RAM, local disk). See InstanceFlavor. |
| `currentState.flavor.bandwidth` | publicCloud.instance.FlavorBandwidth | read-only | Network bandwidth of the flavor in Mbit/s. Null when the flavor is not in the catalog. |
| `currentState.flavor.disk` | integer | read-only | Size of the flavor's local root disk in GB |
| `currentState.flavor.gpus` | integer | read-only | Number of physical GPUs provided by the flavor, 0 for flavors without GPU |
| `currentState.flavor.id` | string (uuid) | read-only | Unique identifier of the flavor |
| `currentState.flavor.name` | string | read-only | Human-readable flavor name, for example the commercial flavor label |
| `currentState.flavor.ram` | integer | read-only | Amount of RAM provided by the flavor in MB |
| `currentState.flavor.vcpus` | integer | read-only | Number of virtual CPUs provided by the flavor |
| `currentState.group` | publicCloud.instance.InstanceGroupRef | read-only | Reference to the instance (placement) group the instance belongs to. Null when it is not part of any group. Immutable after creation. |
| `currentState.group.id` | string (uuid) | yes | Identifier of the instance group. Honored only at creation time. The group cannot be changed afterward. |
| `currentState.hostId` | string | read-only | Opaque identifier of the physical host the instance is running on, as exposed by OpenStack. Null when not available. |
| `currentState.image` | publicCloud.instance.InstanceImage | read-only | Observed image the instance was booted from, with full details (name, size, status). Null for boot-from-volume instances, which have no image. See InstanceImage. |
| `currentState.image.defaultUser` | string | read-only | Default login user of the image, as set by its publisher, for example almalinux or ubuntu. Null when the image declares none. |
| `currentState.image.deprecated` | boolean | read-only | Whether the image is flagged as deprecated. A deprecated image can still boot existing instances but is no longer recommended for new ones. |
| `currentState.image.id` | string (uuid) | read-only | Unique identifier of the image |
| `currentState.image.name` | string | read-only | Human-readable image name. Null when not reported by the backend. |
| `currentState.image.size` | integer | read-only | Size of the image in bytes. Null when the backend does not report it. |
| `currentState.image.status` | publicCloud.instance.ImageStatusEnum | read-only | Lifecycle status of the image as reported by Glance (see ImageStatusEnum). Null when not reported. — one of `ACTIVE`, `DEACTIVATED`, `DELETED`, `IMPORTING`, `KILLED`, `PENDING_DELETE`, `QUEUED`, `SAVING` |
| `currentState.location` | publicCloud.instance.InstanceLocation | read-only | Location. Observed region and availability zone where the instance is provisioned. See InstanceLocation. |
| `currentState.location.availabilityZone` | string |  | Availability zone within the region where the instance is placed. When omitted at creation the backend selects a zone automatically. Immutable after creation. |
| `currentState.location.region` | string | yes | Code of the region where the instance is provisioned, for example GRA11, BHS5. Immutable after creation. An instance cannot be moved to another region. |
| `currentState.locked` | boolean | read-only | Lock state. Whether the instance is locked against modifications. When locked, mutating actions are refused until it is unlocked (see the LOCK/UNLOCK actions in InstanceActionTypeEnum). |
| `currentState.name` | string | read-only | Observed display name of the instance |
| `currentState.networks` | publicCloud.instance.InstanceNetwork[] | read-only | Observed network interfaces of the instance, with full details (network, subnet, gateway and per-interface addresses). One entry per network, plus at most one entry without an id for the public (Ext-Net) interface. Every address of the instance is reported through the entry's addresses list, each address typed FIXED, FLOATING or ADDITIONAL. There is no separate scalar address field. See InstanceNetwork. |
| `currentState.networks[].addresses` | publicCloud.instance.InstanceNetworkAddress[] | read-only | Every IP address through which the instance is reachable on this interface, each with its type, IP version and MAC address. It carries the interface's fixed addresses and, where applicable, the floating IP associated with it and any additional IPs routed to it. This is the single source of truth for the instance's observed addresses. Null or empty only while no address has been assigned yet. See InstanceNetworkAddress. |
| `currentState.networks[].gatewayId` | string (uuid) | read-only | Identifier of the gateway providing egress for this interface. Null when none applies. |
| `currentState.networks[].id` | string (uuid) | read-only | Identifier of the network this interface is attached to, or null for the public (Ext-Net) interface. There is at most one entry without an id: additional IPs are reported as ADDITIONAL addresses of that public entry instead of forming their own entry. |
| `currentState.networks[].subnetId` | string (uuid) | read-only | Identifier of the subnet this interface draws its fixed address from, or null for an entry without a network id |
| `currentState.powerState` | publicCloud.instance.PowerStateEnum | read-only | Actual administrative power state of the instance as reported by OpenStack (see PowerStateEnum). This may transiently differ from targetSpec.powerState while a power transition is in progress. — one of `ACTIVE`, `PAUSED`, `RESCUE`, `SHELVED`, `SHUTOFF`, `SUSPENDED` |
| `currentState.projectId` | string | read-only | Identifier of the Public Cloud project the instance belongs to |
| `currentState.securityGroups` | publicCloud.securityGroup.SecurityGroupRef[] | read-only | References to the security groups currently attached to the instance's ports |
| `currentState.securityGroups[].id` | string (uuid) | yes | Identifier of the security group |
| `currentState.shares` | publicCloud.instance.InstanceShare[] | read-only | Observed instance-side share attachments. Only populated on a GET of a single instance (never in list responses). Mixing per-share access rules (managed directly on the share resource) with instance-side attach on the same share is unsupported and will show the share OUT_OF_SYNC. See InstanceShare. |
| `currentState.shares[].accessLevel` | publicCloud.storage.file.FileStorageAccessLevelEnum | read-only | Observed access level of the access rule for this instance (see FileStorageAccessLevelEnum: READ_ONLY, READ_WRITE) — one of `READ_ONLY`, `READ_WRITE` |
| `currentState.shares[].accessTo` | string | read-only | The instance IP address the Manila access rule targets. The instance's fixed IPv4 address on the share's network. |
| `currentState.shares[].id` | string (uuid) | read-only | Identifier of the attached file storage (share) |
| `currentState.shares[].state` | publicCloud.storage.file.FileStorageAccessRuleStateEnum | read-only | Observed state of the underlying access rule (see FileStorageAccessRuleStateEnum: ACTIVE, APPLYING, DENYING, ERROR). Null while no state has been reported yet. — one of `ACTIVE`, `APPLYING`, `DENYING`, `ERROR` |
| `currentState.sshKeyName` | string | read-only | Name of the SSH key pair injected into the instance at boot. Null when none was provided. |
| `currentState.userId` | string | read-only | Identifier of the OpenStack user that owns the instance |
| `currentState.volumes` | publicCloud.instance.InstanceVolume[] | read-only | Observed block volumes attached to the instance, with details (name, size). See InstanceVolume. |
| `currentState.volumes[].id` | string (uuid) | read-only | Unique identifier of the attached volume |
| `currentState.volumes[].name` | string | read-only | Display name of the attached volume |
| `currentState.volumes[].size` | integer | read-only | Size of the attached volume in GB |
| `currentTasks` | common.CurrentTask[] | read-only | In-progress operations. Ongoing asynchronous tasks reconciling currentState toward targetSpec, for example a create, resize, reboot, volume attach or share attach. Poll the instance until this list is empty and resourceStatus is READY to know the requested change has been applied. |
| `currentTasks[].errors` | common.TaskError[] | read-only | Errors that occurred on the task |
| `currentTasks[].errors[].message` | string | read-only | Error description |
| `currentTasks[].id` | string (uuid) | read-only | Identifier of the current task |
| `currentTasks[].link` | string | read-only | Link to the task details |
| `currentTasks[].status` | common.CurrentTaskStatusEnum | read-only | Current global status of the current task — one of `ERROR`, `PENDING`, `RUNNING`, `SCHEDULED`, `WAITING_USER_INPUT` |
| `currentTasks[].type` | string | read-only | Type of the current task |
| `id` | string (uuid) | read-only | Unique identifier of the instance |
| `resourceStatus` | common.ResourceStatusEnum | read-only | Resource lifecycle status. High-level readiness of the instance in the system, for example CREATING, READY, UPDATING, DELETING, ERROR. This is distinct from currentState.powerState, which carries the lower-level OpenStack administrative power state of the virtual machine. — one of `CREATING`, `CREATION_PLANNED`, `DELETING`, `ERROR`, `OUT_OF_SYNC`, `READY`, `SUSPENDED`, `UNKNOWN`, `UPDATING` |
| `targetSpec` | publicCloud.instance.InstanceReadTargetSpec | read-only | Desired specification. Last target specification requested for the instance. On update, the difference between the previous and the new targetSpec determines the operations performed (rename, resize, power change, and declarative volume/share attach-detach). |
| `targetSpec.flavor` | publicCloud.instance.InstanceFlavorRef | read-only | Reference to the flavor that sizes the instance (vCPUs, RAM, local disk). Carries only the flavor id. Changing the referenced flavor on PUT triggers a resize of the instance. |
| `targetSpec.flavor.id` | string (uuid) | yes | Identifier of the flavor to size the instance with. Changing it on update triggers a resize. |
| `targetSpec.group` | publicCloud.instance.InstanceGroupRef | read-only | Optional reference to the instance (placement) group the instance is created into, controlling affinity/anti-affinity placement. Immutable: the group is set only at creation time. OpenStack/Nova server groups are immutable. There is no group change on PUT and membership cannot be changed after the instance exists. |
| `targetSpec.group.id` | string (uuid) | yes | Identifier of the instance group. Honored only at creation time. The group cannot be changed afterward. |
| `targetSpec.image` | publicCloud.instance.InstanceImageRef | read-only | Reference to the image the instance boots from. Carries only the image id. Changing the referenced image on PUT triggers a rebuild of the instance from the new image. Null for boot-from-volume instances, which have no backing image. |
| `targetSpec.image.id` | string (uuid) | yes | Identifier of the image to boot from. Changing it on update triggers a rebuild of the instance. |
| `targetSpec.location` | publicCloud.instance.InstanceLocation | read-only | Target location. Region (and optional availability zone) where the instance is provisioned. Immutable after creation. An instance cannot be moved to another region/zone, which is why location is absent from InstanceUpdateTargetSpec. |
| `targetSpec.location.availabilityZone` | string |  | Availability zone within the region where the instance is placed. When omitted at creation the backend selects a zone automatically. Immutable after creation. |
| `targetSpec.location.region` | string | yes | Code of the region where the instance is provisioned, for example GRA11, BHS5. Immutable after creation. An instance cannot be moved to another region. |
| `targetSpec.name` | string | read-only | Desired display name of the instance. Changing it on PUT triggers a rename. |
| `targetSpec.networks` | publicCloud.instance.InstanceNetworkRef[] | read-only | Declarative list of network interfaces the instance is attached to. An entry with a subnetId, and an optional id, is a private interface, optionally carrying an ip to pin its fixed address or to associate an existing floating IP. An entry with autoAssignPublicIp alone requests a public (Ext-Net) interface with a platform-assigned public IP. An entry with ip alone attaches a public IP the project already owns, either an additional IP or an Ext-Net IP of the project in the instance's region. See InstanceNetworkRef. The list drives the desired network topology: adding or removing an entry attaches or detaches the corresponding interface on update. |
| `targetSpec.networks[].autoAssignPublicIp` | boolean |  | Auto-assign public IP. Whether to attach a public (Ext-Net) interface with a public IP assigned by the platform. Only allowed on an entry that has no id, no subnetId and no ip, and at most one entry of the networks list may set it. Requires the optional instance/usePublicIP IAM action. |
| `targetSpec.networks[].id` | string (uuid) |  | Identifier of the private network to attach to. Optional on a private interface: when omitted, the network of subnetId is used. Omit it on an entry declaring public connectivity through autoAssignPublicIp or ip. |
| `targetSpec.networks[].ip` | ip |  | Address of this interface, whose meaning depends on the sibling fields. Without an id and a subnetId: a public IP the project already owns. An additional IP, or an Ext-Net IP of the project in the instance's region. Any other address is rejected, and the entry implicitly attaches the public (Ext-Net) interface. On a private entry (subnetId, with an optional id): pins the interface's fixed address when the address falls inside the subnet CIDR, and otherwise designates an EXISTING floating IP to associate with that interface. A public address requires the optional instance/usePublicIP IAM action. |
| `targetSpec.networks[].subnetId` | string (uuid) |  | Identifier of the subnet the interface draws its fixed address from. Required for a private interface. Leave unset on an entry declaring public connectivity. |
| `targetSpec.powerState` | publicCloud.instance.PowerStateEnum | read-only | Desired administrative power state of the instance (see PowerStateEnum: ACTIVE, PAUSED, RESCUE, SHELVED, SHUTOFF, SUSPENDED). Changing it on PUT drives the corresponding power transition (start, stop, shelve, rescue, pause, suspend). Defaults to ACTIVE. — one of `ACTIVE`, `PAUSED`, `RESCUE`, `SHELVED`, `SHUTOFF`, `SUSPENDED` |
| `targetSpec.securityGroups` | publicCloud.securityGroup.SecurityGroupRef[] | read-only | Optional list of references to the security groups applied to all of the instance's ports. Each entry carries the security group id. Changing this list on PUT re-applies the resulting set of security groups to every instance port. |
| `targetSpec.securityGroups[].id` | string (uuid) | yes | Identifier of the security group |
| `targetSpec.shares` | publicCloud.instance.InstanceShareRef[] | read-only | Declarative list of file storage (shares) attached to the instance, managed exactly like volumes: the diff of this list on PUT drives attach/detach. Attaching a share creates a Manila IP access rule for the instance's interface on the share's network. The instance must have an interface on that network or the operation errors. Detaching (removing an entry from this list) deletes the matching access rule and is idempotent. Each entry's accessLevel defaults to READ_WRITE when omitted (see InstanceShareRef). |
| `targetSpec.shares[].accessLevel` | publicCloud.storage.file.FileStorageAccessLevelEnum |  | Desired access level granted to the instance for this share (see FileStorageAccessLevelEnum: READ_ONLY, READ_WRITE). Defaults to READ_WRITE. — one of `READ_ONLY`, `READ_WRITE` |
| `targetSpec.shares[].id` | string (uuid) | yes | Identifier of the file storage (share) to attach. Adding this reference attaches the share to the instance. Removing it from the shares list detaches it. |
| `targetSpec.sshKeyName` | string | read-only | Name of the SSH key pair injected into the instance at boot for initial access. Immutable / create-only: the key is injected once during provisioning and cannot be changed afterward, which is why sshKeyName is absent from InstanceUpdateTargetSpec. |
| `targetSpec.volumes` | publicCloud.instance.InstanceVolumeRef[] | read-only | Declarative list of block volumes attached to the instance, each referencing a volume by id (see InstanceVolumeRef). Attach/detach is driven by diffing this list on PUT. There is no imperative attach/detach sub-route. Adding a volume reference attaches that volume. Removing one detaches it. |
| `targetSpec.volumes[].id` | string (uuid) | yes | Identifier of the volume to attach. Adding this reference attaches the volume. Removing it from the volumes list detaches it. |
| `updatedAt` | string (date-time) | read-only | Last modification date of the instance, as an ISO 8601 / RFC 3339 timestamp |

```json
[
  {
    "checksum": "string",
    "createdAt": "2024-01-01T12:00:00Z",
    "currentState": {
      "availableActions": [
        {
          "available": true,
          "name": "LOCK"
        }
      ],
      "flavor": {
        "bandwidth": {
          "private": 0,
          "publicInbound": 0,
          "publicOutbound": 0
        },
        "disk": 0,
        "gpus": 0,
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "string",
        "ram": 0,
        "vcpus": 0
      },
      "group": {
        "id": "00000000-0000-0000-0000-000000000000"
      },
      "hostId": "string",
      "image": {
        "defaultUser": "string",
        "deprecated": true,
        "id": "00000000-0000-0000-0000-000000000000",
        "name": "string",
        "size": 0,
        "status": "ACTIVE"
      },
      "location": {
        "availabilityZone": "string",
        "region": "string"
      },
      "locked": true,
      "name": "string",
      "networks": [
        {
          "addresses": [
            {
              "ip": null,
              "mac": null,
              "type": null,
              "version": null
            }
          ],
          "gatewayId": "00000000-0000-0000-0000-000000000000",
          "id": "00000000-0000-0000-0000-000000000000",
          "subnetId": "00000000-0000-0000-0000-000000000000"
        }
      ],
      "powerState": "ACTIVE",
      "projectId": "string",
      "securityGroups": [
        {
          "id": "00000000-0000-0000-0000-000000000000"
        }
      ],
      "shares": [
        {
  …
```

### Example

```bash
curl -X GET \
  "https://api.eu.ovhcloud.com/v2/publicCloud/project/{projectId}/compute/instance" \
  -H "accept: application/json" \
  -H "authorization: Bearer $OVH_TOKEN"
```

```python
'''
First, install the latest release of Python wrapper: $ pip install ovh
'''
import json
import ovh

# Instantiate an OVH Client.
# You can generate new credentials with full access to your account on
# the token creation page (https://api.ovh.com/createToken/index.cgi?GET=/*&PUT=/*&POST=/*&DELETE=/*)
client = ovh.Client(
	endpoint='ovh-eu',               # Endpoint of API OVH (List of available endpoints: https://github.com/ovh/python-ovh#2-configure-your-application)
	application_key='xxxxxxxxxx',    # Application Key
	application_secret='xxxxxxxxxx', # Application Secret
	consumer_key='xxxxxxxxxx',       # Consumer Key
)

result = client.get("/v2/publicCloud/project/{projectId}/compute/instance")

# Pretty print
print(json.dumps(result, indent=4))
```

```php
<?php
/**
 * First, download the latest release of PHP wrapper on github
 * And include this script into the folder with extracted files
 */
require __DIR__ . '/vendor/autoload.php';
use \Ovh\Api;

/**
 * Instantiate an OVH Client.
 * You can generate new credentials with full access to your account on
 * the token creation page (https://api.ovh.com/createToken/index.cgi?GET=/*&PUT=/*&POST=/*&DELETE=/*)
 */
$ovh = new Api('xxxxxxxxxx',  // Application Key
               'xxxxxxxxxx',  // Application Secret
               'ovh-eu',      // Endpoint of API OVH (List of available endpoints: https://github.com/ovh/python-ovh#2-configure-your-application)
               'xxxxxxxxxx'); // Consumer Key

$result = $ovh->get("/v2/publicCloud/project/{projectId}/compute/instance");

print_r($result);
?>
```

## Get an instance

`GET /v2/publicCloud/project/{projectId}/compute/instance/{instanceId}`

Link: https://developers.eu.ovhcloud.com/reference/public-cloud/compute/instances/#getInstance

**Status:** Stable production version  
**IAM actions:** `publicCloudProject:apiovh:instance/get`

### Get an instance

Returns a single Public Cloud instance, including its desired `targetSpec` and observed `currentState`.

### Optimistic concurrency
The `checksum` returned here is the hash of the current `targetSpec`. Keep it and send it back on any subsequent `PUT` or imperative `action` call on the instance to guard against lost updates. It is optional, but omitting it forces the write (see the `PUT` route).

### Filesystem attachments
`currentState.shares` — the list of filesystems (Manila shares) attached to the instance — is populated only on this single-instance `GET`. It is deliberately not returned by the `LIST` route for performance reasons. Fetch the individual instance when you need it.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `instanceId` | path | string (uuid) | yes | Instance ID |
| `projectId` | path | string | yes | Project ID |

### Responses

| Status | Type | Description |
| --- | --- | --- |
| 200 | publicCloud.instance.Instance | successful operation |
| 404 | object | Error 404 response |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `checksum` | string | read-only | Computed hash representing the current targetSpec value. It enables optional optimistic concurrency control: the value returned by a GET may be sent back in the PUT and action payloads, and the request is then rejected with a 409 checksum-mismatch conflict if it no longer matches server-side (because another request modified the instance in the meantime). Sending no checksum skips that check and forces the write (last-write-wins). |
| `createdAt` | string (date-time) | read-only | Creation date of the instance, as an ISO 8601 / RFC 3339 timestamp |
| `currentState` | publicCloud.instance.InstanceCurrentState | read-only | Current observed state of the instance as reported by the compute backend (name, flavor, image, location, power state, networks, attached volumes, attached shares, security groups). It is null while the instance is still being created and no backend state is available yet. |
| `currentState.availableActions` | publicCloud.instance.InstanceAvailableAction[] | read-only | Availability of every instance action type given the current state of the instance. Always contains exactly one entry per InstanceActionTypeEnum value, in the order of that enum, each flagged with whether it can currently be triggered through the action endpoint. For example, when the instance is locked only UNLOCK is available. While a task is in progress on the instance or when it is in error, none is available. |
| `currentState.availableActions[].available` | boolean | read-only | Whether the action can currently be triggered through the action endpoint. A call with an unavailable action is refused. |
| `currentState.availableActions[].name` | publicCloud.instance.InstanceActionTypeEnum | read-only | Action type, as accepted by the action endpoint — one of `LOCK`, `PAUSE`, `REBOOT`, `RESCUE`, `RESUME`, `SHELVE`, `START`, `STOP`, `SUSPEND`, `UNLOCK`, `UNPAUSE`, `UNRESCUE`, … |
| `currentState.flavor` | publicCloud.instance.InstanceFlavor | read-only | Observed flavor of the instance with full details (name, vCPUs, RAM, local disk). See InstanceFlavor. |
| `currentState.flavor.bandwidth` | publicCloud.instance.FlavorBandwidth | read-only | Network bandwidth of the flavor in Mbit/s. Null when the flavor is not in the catalog. |
| `currentState.flavor.disk` | integer | read-only | Size of the flavor's local root disk in GB |
| `currentState.flavor.gpus` | integer | read-only | Number of physical GPUs provided by the flavor, 0 for flavors without GPU |
| `currentState.flavor.id` | string (uuid) | read-only | Unique identifier of the flavor |
| `currentState.flavor.name` | string | read-only | Human-readable flavor name, for example the commercial flavor label |
| `currentState.flavor.ram` | integer | read-only | Amount of RAM provided by the flavor in MB |
| `currentState.flavor.vcpus` | integer | read-only | Number of virtual CPUs provided by the flavor |
| `currentState.group` | publicCloud.instance.InstanceGroupRef | read-only | Reference to the instance (placement) group the instance belongs to. Null when it is not part of any group. Immutable after creation. |
| `currentState.group.id` | string (uuid) | yes | Identifier of the instance group. Honored only at creation time. The group cannot be changed afterward. |
| `currentState.hostId` | string | read-only | Opaque identifier of the physical host the instance is running on, as exposed by OpenStack. Null when not available. |
| `currentState.image` | publicCloud.instance.InstanceImage | read-only | Observed image the instance was booted from, with full details (name, size, status). Null for boot-from-volume instances, which have no image. See InstanceImage. |
| `currentState.image.defaultUser` | string | read-only | Default login user of the image, as set by its publisher, for example almalinux or ubuntu. Null when the image declares none. |
| `currentState.image.deprecated` | boolean | read-only | Whether the image is flagged as deprecated. A deprecated image can still boot existing instances but is no longer recommended for new ones. |
| `currentState.image.id` | string (uuid) | read-only | Unique identifier of the image |
| `currentState.image.name` | string | read-only | Human-readable image name. Null when not reported by the backend. |
| `currentState.image.size` | integer | read-only | Size of the image in bytes. Null when the backend does not report it. |
| `currentState.image.status` | publicCloud.instance.ImageStatusEnum | read-only | Lifecycle status of the image as reported by Glance (see ImageStatusEnum). Null when not reported. — one of `ACTIVE`, `DEACTIVATED`, `DELETED`, `IMPORTING`, `KILLED`, `PENDING_DELETE`, `QUEUED`, `SAVING` |
| `currentState.location` | publicCloud.instance.InstanceLocation | read-only | Location. Observed region and availability zone where the instance is provisioned. See InstanceLocation. |
| `currentState.location.availabilityZone` | string |  | Availability zone within the region where the instance is placed. When omitted at creation the backend selects a zone automatically. Immutable after creation. |
| `currentState.location.region` | string | yes | Code of the region where the instance is provisioned, for example GRA11, BHS5. Immutable after creation. An instance cannot be moved to another region. |
| `currentState.locked` | boolean | read-only | Lock state. Whether the instance is locked against modifications. When locked, mutating actions are refused until it is unlocked (see the LOCK/UNLOCK actions in InstanceActionTypeEnum). |
| `currentState.name` | string | read-only | Observed display name of the instance |
| `currentState.networks` | publicCloud.instance.InstanceNetwork[] | read-only | Observed network interfaces of the instance, with full details (network, subnet, gateway and per-interface addresses). One entry per network, plus at most one entry without an id for the public (Ext-Net) interface. Every address of the instance is reported through the entry's addresses list, each address typed FIXED, FLOATING or ADDITIONAL. There is no separate scalar address field. See InstanceNetwork. |
| `currentState.networks[].addresses` | publicCloud.instance.InstanceNetworkAddress[] | read-only | Every IP address through which the instance is reachable on this interface, each with its type, IP version and MAC address. It carries the interface's fixed addresses and, where applicable, the floating IP associated with it and any additional IPs routed to it. This is the single source of truth for the instance's observed addresses. Null or empty only while no address has been assigned yet. See InstanceNetworkAddress. |
| `currentState.networks[].gatewayId` | string (uuid) | read-only | Identifier of the gateway providing egress for this interface. Null when none applies. |
| `currentState.networks[].id` | string (uuid) | read-only | Identifier of the network this interface is attached to, or null for the public (Ext-Net) interface. There is at most one entry without an id: additional IPs are reported as ADDITIONAL addresses of that public entry instead of forming their own entry. |
| `currentState.networks[].subnetId` | string (uuid) | read-only | Identifier of the subnet this interface draws its fixed address from, or null for an entry without a network id |
| `currentState.powerState` | publicCloud.instance.PowerStateEnum | read-only | Actual administrative power state of the instance as reported by OpenStack (see PowerStateEnum). This may transiently differ from targetSpec.powerState while a power transition is in progress. — one of `ACTIVE`, `PAUSED`, `RESCUE`, `SHELVED`, `SHUTOFF`, `SUSPENDED` |
| `currentState.projectId` | string | read-only | Identifier of the Public Cloud project the instance belongs to |
| `currentState.securityGroups` | publicCloud.securityGroup.SecurityGroupRef[] | read-only | References to the security groups currently attached to the instance's ports |
| `currentState.securityGroups[].id` | string (uuid) | yes | Identifier of the security group |
| `currentState.shares` | publicCloud.instance.InstanceShare[] | read-only | Observed instance-side share attachments. Only populated on a GET of a single instance (never in list responses). Mixing per-share access rules (managed directly on the share resource) with instance-side attach on the same share is unsupported and will show the share OUT_OF_SYNC. See InstanceShare. |
| `currentState.shares[].accessLevel` | publicCloud.storage.file.FileStorageAccessLevelEnum | read-only | Observed access level of the access rule for this instance (see FileStorageAccessLevelEnum: READ_ONLY, READ_WRITE) — one of `READ_ONLY`, `READ_WRITE` |
| `currentState.shares[].accessTo` | string | read-only | The instance IP address the Manila access rule targets. The instance's fixed IPv4 address on the share's network. |
| `currentState.shares[].id` | string (uuid) | read-only | Identifier of the attached file storage (share) |
| `currentState.shares[].state` | publicCloud.storage.file.FileStorageAccessRuleStateEnum | read-only | Observed state of the underlying access rule (see FileStorageAccessRuleStateEnum: ACTIVE, APPLYING, DENYING, ERROR). Null while no state has been reported yet. — one of `ACTIVE`, `APPLYING`, `DENYING`, `ERROR` |
| `currentState.sshKeyName` | string | read-only | Name of the SSH key pair injected into the instance at boot. Null when none was provided. |
| `currentState.userId` | string | read-only | Identifier of the OpenStack user that owns the instance |
| `currentState.volumes` | publicCloud.instance.InstanceVolume[] | read-only | Observed block volumes attached to the instance, with details (name, size). See InstanceVolume. |
| `currentState.volumes[].id` | string (uuid) | read-only | Unique identifier of the attached volume |
| `currentState.volumes[].name` | string | read-only | Display name of the attached volume |
| `currentState.volumes[].size` | integer | read-only | Size of the attached volume in GB |
| `currentTasks` | common.CurrentTask[] | read-only | In-progress operations. Ongoing asynchronous tasks reconciling currentState toward targetSpec, for example a create, resize, reboot, volume attach or share attach. Poll the instance until this list is empty and resourceStatus is READY to know the requested change has been applied. |
| `currentTasks[].errors` | common.TaskError[] | read-only | Errors that occurred on the task |
| `currentTasks[].errors[].message` | string | read-only | Error description |
| `currentTasks[].id` | string (uuid) | read-only | Identifier of the current task |
| `currentTasks[].link` | string | read-only | Link to the task details |
| `currentTasks[].status` | common.CurrentTaskStatusEnum | read-only | Current global status of the current task — one of `ERROR`, `PENDING`, `RUNNING`, `SCHEDULED`, `WAITING_USER_INPUT` |
| `currentTasks[].type` | string | read-only | Type of the current task |
| `id` | string (uuid) | read-only | Unique identifier of the instance |
| `resourceStatus` | common.ResourceStatusEnum | read-only | Resource lifecycle status. High-level readiness of the instance in the system, for example CREATING, READY, UPDATING, DELETING, ERROR. This is distinct from currentState.powerState, which carries the lower-level OpenStack administrative power state of the virtual machine. — one of `CREATING`, `CREATION_PLANNED`, `DELETING`, `ERROR`, `OUT_OF_SYNC`, `READY`, `SUSPENDED`, `UNKNOWN`, `UPDATING` |
| `targetSpec` | publicCloud.instance.InstanceReadTargetSpec | read-only | Desired specification. Last target specification requested for the instance. On update, the difference between the previous and the new targetSpec determines the operations performed (rename, resize, power change, and declarative volume/share attach-detach). |
| `targetSpec.flavor` | publicCloud.instance.InstanceFlavorRef | read-only | Reference to the flavor that sizes the instance (vCPUs, RAM, local disk). Carries only the flavor id. Changing the referenced flavor on PUT triggers a resize of the instance. |
| `targetSpec.flavor.id` | string (uuid) | yes | Identifier of the flavor to size the instance with. Changing it on update triggers a resize. |
| `targetSpec.group` | publicCloud.instance.InstanceGroupRef | read-only | Optional reference to the instance (placement) group the instance is created into, controlling affinity/anti-affinity placement. Immutable: the group is set only at creation time. OpenStack/Nova server groups are immutable. There is no group change on PUT and membership cannot be changed after the instance exists. |
| `targetSpec.group.id` | string (uuid) | yes | Identifier of the instance group. Honored only at creation time. The group cannot be changed afterward. |
| `targetSpec.image` | publicCloud.instance.InstanceImageRef | read-only | Reference to the image the instance boots from. Carries only the image id. Changing the referenced image on PUT triggers a rebuild of the instance from the new image. Null for boot-from-volume instances, which have no backing image. |
| `targetSpec.image.id` | string (uuid) | yes | Identifier of the image to boot from. Changing it on update triggers a rebuild of the instance. |
| `targetSpec.location` | publicCloud.instance.InstanceLocation | read-only | Target location. Region (and optional availability zone) where the instance is provisioned. Immutable after creation. An instance cannot be moved to another region/zone, which is why location is absent from InstanceUpdateTargetSpec. |
| `targetSpec.location.availabilityZone` | string |  | Availability zone within the region where the instance is placed. When omitted at creation the backend selects a zone automatically. Immutable after creation. |
| `targetSpec.location.region` | string | yes | Code of the region where the instance is provisioned, for example GRA11, BHS5. Immutable after creation. An instance cannot be moved to another region. |
| `targetSpec.name` | string | read-only | Desired display name of the instance. Changing it on PUT triggers a rename. |
| `targetSpec.networks` | publicCloud.instance.InstanceNetworkRef[] | read-only | Declarative list of network interfaces the instance is attached to. An entry with a subnetId, and an optional id, is a private interface, optionally carrying an ip to pin its fixed address or to associate an existing floating IP. An entry with autoAssignPublicIp alone requests a public (Ext-Net) interface with a platform-assigned public IP. An entry with ip alone attaches a public IP the project already owns, either an additional IP or an Ext-Net IP of the project in the instance's region. See InstanceNetworkRef. The list drives the desired network topology: adding or removing an entry attaches or detaches the corresponding interface on update. |
| `targetSpec.networks[].autoAssignPublicIp` | boolean |  | Auto-assign public IP. Whether to attach a public (Ext-Net) interface with a public IP assigned by the platform. Only allowed on an entry that has no id, no subnetId and no ip, and at most one entry of the networks list may set it. Requires the optional instance/usePublicIP IAM action. |
| `targetSpec.networks[].id` | string (uuid) |  | Identifier of the private network to attach to. Optional on a private interface: when omitted, the network of subnetId is used. Omit it on an entry declaring public connectivity through autoAssignPublicIp or ip. |
| `targetSpec.networks[].ip` | ip |  | Address of this interface, whose meaning depends on the sibling fields. Without an id and a subnetId: a public IP the project already owns. An additional IP, or an Ext-Net IP of the project in the instance's region. Any other address is rejected, and the entry implicitly attaches the public (Ext-Net) interface. On a private entry (subnetId, with an optional id): pins the interface's fixed address when the address falls inside the subnet CIDR, and otherwise designates an EXISTING floating IP to associate with that interface. A public address requires the optional instance/usePublicIP IAM action. |
| `targetSpec.networks[].subnetId` | string (uuid) |  | Identifier of the subnet the interface draws its fixed address from. Required for a private interface. Leave unset on an entry declaring public connectivity. |
| `targetSpec.powerState` | publicCloud.instance.PowerStateEnum | read-only | Desired administrative power state of the instance (see PowerStateEnum: ACTIVE, PAUSED, RESCUE, SHELVED, SHUTOFF, SUSPENDED). Changing it on PUT drives the corresponding power transition (start, stop, shelve, rescue, pause, suspend). Defaults to ACTIVE. — one of `ACTIVE`, `PAUSED`, `RESCUE`, `SHELVED`, `SHUTOFF`, `SUSPENDED` |
| `targetSpec.securityGroups` | publicCloud.securityGroup.SecurityGroupRef[] | read-only | Optional list of references to the security groups applied to all of the instance's ports. Each entry carries the security group id. Changing this list on PUT re-applies the resulting set of security groups to every instance port. |
| `targetSpec.securityGroups[].id` | string (uuid) | yes | Identifier of the security group |
| `targetSpec.shares` | publicCloud.instance.InstanceShareRef[] | read-only | Declarative list of file storage (shares) attached to the instance, managed exactly like volumes: the diff of this list on PUT drives attach/detach. Attaching a share creates a Manila IP access rule for the instance's interface on the share's network. The instance must have an interface on that network or the operation errors. Detaching (removing an entry from this list) deletes the matching access rule and is idempotent. Each entry's accessLevel defaults to READ_WRITE when omitted (see InstanceShareRef). |
| `targetSpec.shares[].accessLevel` | publicCloud.storage.file.FileStorageAccessLevelEnum |  | Desired access level granted to the instance for this share (see FileStorageAccessLevelEnum: READ_ONLY, READ_WRITE). Defaults to READ_WRITE. — one of `READ_ONLY`, `READ_WRITE` |
| `targetSpec.shares[].id` | string (uuid) | yes | Identifier of the file storage (share) to attach. Adding this reference attaches the share to the instance. Removing it from the shares list detaches it. |
| `targetSpec.sshKeyName` | string | read-only | Name of the SSH key pair injected into the instance at boot for initial access. Immutable / create-only: the key is injected once during provisioning and cannot be changed afterward, which is why sshKeyName is absent from InstanceUpdateTargetSpec. |
| `targetSpec.volumes` | publicCloud.instance.InstanceVolumeRef[] | read-only | Declarative list of block volumes attached to the instance, each referencing a volume by id (see InstanceVolumeRef). Attach/detach is driven by diffing this list on PUT. There is no imperative attach/detach sub-route. Adding a volume reference attaches that volume. Removing one detaches it. |
| `targetSpec.volumes[].id` | string (uuid) | yes | Identifier of the volume to attach. Adding this reference attaches the volume. Removing it from the volumes list detaches it. |
| `updatedAt` | string (date-time) | read-only | Last modification date of the instance, as an ISO 8601 / RFC 3339 timestamp |

```json
{
  "checksum": "string",
  "createdAt": "2024-01-01T12:00:00Z",
  "currentState": {
    "availableActions": [
      {
        "available": true,
        "name": "LOCK"
      }
    ],
    "flavor": {
      "bandwidth": {
        "private": 0,
        "publicInbound": 0,
        "publicOutbound": 0
      },
      "disk": 0,
      "gpus": 0,
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "string",
      "ram": 0,
      "vcpus": 0
    },
    "group": {
      "id": "00000000-0000-0000-0000-000000000000"
    },
    "hostId": "string",
    "image": {
      "defaultUser": "string",
      "deprecated": true,
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "string",
      "size": 0,
      "status": "ACTIVE"
    },
    "location": {
      "availabilityZone": "string",
      "region": "string"
    },
    "locked": true,
    "name": "string",
    "networks": [
      {
        "addresses": [
          {
            "ip": "192.0.2.0",
            "mac": "00:00:5e:00:53:01",
            "type": "ADDITIONAL",
            "version": 0
          }
        ],
        "gatewayId": "00000000-0000-0000-0000-000000000000",
        "id": "00000000-0000-0000-0000-000000000000",
        "subnetId": "00000000-0000-0000-0000-000000000000"
      }
    ],
    "powerState": "ACTIVE",
    "projectId": "string",
    "securityGroups": [
      {
        "id": "00000000-0000-0000-0000-000000000000"
      }
    ],
    "shares": [
      {
        "accessLevel": "READ_ONLY",
        "accessTo": "string",
        "id": "00000000-0000-0000-0000-000000000000",
  …
```

### Example

```bash
curl -X GET \
  "https://api.eu.ovhcloud.com/v2/publicCloud/project/{projectId}/compute/instance/{instanceId}" \
  -H "accept: application/json" \
  -H "authorization: Bearer $OVH_TOKEN"
```

```python
'''
First, install the latest release of Python wrapper: $ pip install ovh
'''
import json
import ovh

# Instantiate an OVH Client.
# You can generate new credentials with full access to your account on
# the token creation page (https://api.ovh.com/createToken/index.cgi?GET=/*&PUT=/*&POST=/*&DELETE=/*)
client = ovh.Client(
	endpoint='ovh-eu',               # Endpoint of API OVH (List of available endpoints: https://github.com/ovh/python-ovh#2-configure-your-application)
	application_key='xxxxxxxxxx',    # Application Key
	application_secret='xxxxxxxxxx', # Application Secret
	consumer_key='xxxxxxxxxx',       # Consumer Key
)

result = client.get("/v2/publicCloud/project/{projectId}/compute/instance/{instanceId}")

# Pretty print
print(json.dumps(result, indent=4))
```

```php
<?php
/**
 * First, download the latest release of PHP wrapper on github
 * And include this script into the folder with extracted files
 */
require __DIR__ . '/vendor/autoload.php';
use \Ovh\Api;

/**
 * Instantiate an OVH Client.
 * You can generate new credentials with full access to your account on
 * the token creation page (https://api.ovh.com/createToken/index.cgi?GET=/*&PUT=/*&POST=/*&DELETE=/*)
 */
$ovh = new Api('xxxxxxxxxx',  // Application Key
               'xxxxxxxxxx',  // Application Secret
               'ovh-eu',      // Endpoint of API OVH (List of available endpoints: https://github.com/ovh/python-ovh#2-configure-your-application)
               'xxxxxxxxxx'); // Consumer Key

$result = $ovh->get("/v2/publicCloud/project/{projectId}/compute/instance/{instanceId}");

print_r($result);
?>
```

## List compatible flavors

`GET /v2/publicCloud/project/{projectId}/compute/instance/{instanceId}/compatibleFlavor`

Link: https://developers.eu.ovhcloud.com/reference/public-cloud/compute/instances/#getInstanceCompatibleFlavors

**Status:** Stable production version  
**IAM actions:** `publicCloudProject:apiovh:instance/compatibleFlavor/get`

### Compatible flavors

Returns the list of flavors this instance can be resized to. The list is computed from the instance's current flavor and the catalog of flavors available in the instance's region.

The following rules apply to the returned list:

- It excludes the instance's current flavor.
- It includes only flavors whose disk size is greater than or equal to the current flavor's disk size (a resize cannot shrink the root disk).
- It includes only flavors in the same region as the instance.
- It includes only flavors whose plan is available in the instance's region.
- It is empty for baremetal instances, which cannot be resized.

Each item has the same shape as an entry from the flavor reference catalog (`publicCloud.reference.instance.Flavor`). Its `location.regionActivated` is true, since the instance's region is activated on the project. `location.availabilityZones` lists the availability zones of the region, for example eu-west-par-a, eu-west-par-b and eu-west-par-c, and is empty for a single-AZ region.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `X-Pagination-Cursor` | header | string |  | Pagination cursor |
| `X-Pagination-Size` | header | integer |  | Pagination size |
| `instanceId` | path | string (uuid) | yes | Instance ID |
| `projectId` | path | string | yes | Project ID |

### Responses

| Status | Type | Description |
| --- | --- | --- |
| 200 | publicCloud.reference.instance.Flavor[] | successful operation |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `bandwidth` | publicCloud.instance.FlavorBandwidth | read-only | Network bandwidth an instance of the flavor gets in Mbit/s |
| `bandwidth.private` | integer | read-only | Bandwidth on private networks (vRack) in Mbit/s. Null when the flavor does not declare it. |
| `bandwidth.publicInbound` | integer | read-only | Inbound bandwidth on the public network in Mbit/s. Null when the flavor does not declare it. |
| `bandwidth.publicOutbound` | integer | read-only | Outbound bandwidth on the public network in Mbit/s. Null when the flavor does not declare it. |
| `description` | string | read-only | Free-form description of the flavor as reported by the backend. Null when no description is advertised for this flavor. |
| `disk` | integer | read-only | Size of the flavor's root disk in GB. This is the primary system disk provisioned for instances created from this flavor. |
| `ephemeral` | integer | read-only | Size of the flavor's ephemeral disk in GB. Ephemeral storage is transient. Its contents do not survive a rebuild or deletion of the instance. Zero when the flavor provides no ephemeral disk. |
| `gpus` | integer | read-only | Number of physical GPUs provided by the flavor. Zero for flavors without GPU. |
| `id` | string (uuid) | read-only | Identifier. The OpenStack/Nova flavor ID. Stable within a region and used to reference the flavor when creating an instance. |
| `isPublic` | boolean | read-only | Public availability. Whether the flavor is publicly available to the project. Private flavors are only visible to the projects they have been explicitly shared with. |
| `location` | publicCloud.reference.Location | read-only | Location. Region where this flavor is offered. The flavor catalog is per-region: a flavor returned for one region is not guaranteed to exist, or to carry the same characteristics, in another. regionActivated tells whether the region is already activated on the project. When false, the region must be activated on the project before use. availabilityZones lists the availability zones of the region, empty for a single-AZ region. |
| `location.availabilityZones` | string[] | read-only | Availability zones of the region, for example eu-west-par-a, eu-west-par-b and eu-west-par-c. Empty for a single-AZ region. |
| `location.region` | string | read-only | Region name, for example GRA11 |
| `location.regionActivated` | boolean | read-only | Whether the region is already activated on the project. When false, the region must be activated on the project before use. |
| `name` | string | read-only | The backend flavor name, for example b2-7, c2-15. This is the commercial/technical name used to identify the sizing in the catalog. |
| `ram` | integer | read-only | RAM in MB. Amount of memory provided by the flavor, expressed in MB. |
| `swap` | integer | read-only | Size of the flavor's swap space in MB. Zero when the flavor provides no swap. |
| `vcpus` | integer | read-only | vCPUs. Number of virtual CPUs provided by the flavor. |

```json
[
  {
    "bandwidth": {
      "private": 0,
      "publicInbound": 0,
      "publicOutbound": 0
    },
    "description": "string",
    "disk": 0,
    "ephemeral": 0,
    "gpus": 0,
    "id": "00000000-0000-0000-0000-000000000000",
    "isPublic": true,
    "location": {
      "availabilityZones": [
        "string"
      ],
      "region": "string",
      "regionActivated": true
    },
    "name": "string",
    "ram": 0,
    "swap": 0,
    "vcpus": 0
  }
]
```

### Example

```bash
curl -X GET \
  "https://api.eu.ovhcloud.com/v2/publicCloud/project/{projectId}/compute/instance/{instanceId}/compatibleFlavor" \
  -H "accept: application/json" \
  -H "authorization: Bearer $OVH_TOKEN"
```

```python
'''
First, install the latest release of Python wrapper: $ pip install ovh
'''
import json
import ovh

# Instantiate an OVH Client.
# You can generate new credentials with full access to your account on
# the token creation page (https://api.ovh.com/createToken/index.cgi?GET=/*&PUT=/*&POST=/*&DELETE=/*)
client = ovh.Client(
	endpoint='ovh-eu',               # Endpoint of API OVH (List of available endpoints: https://github.com/ovh/python-ovh#2-configure-your-application)
	application_key='xxxxxxxxxx',    # Application Key
	application_secret='xxxxxxxxxx', # Application Secret
	consumer_key='xxxxxxxxxx',       # Consumer Key
)

result = client.get("/v2/publicCloud/project/{projectId}/compute/instance/{instanceId}/compatibleFlavor")

# Pretty print
print(json.dumps(result, indent=4))
```

```php
<?php
/**
 * First, download the latest release of PHP wrapper on github
 * And include this script into the folder with extracted files
 */
require __DIR__ . '/vendor/autoload.php';
use \Ovh\Api;

/**
 * Instantiate an OVH Client.
 * You can generate new credentials with full access to your account on
 * the token creation page (https://api.ovh.com/createToken/index.cgi?GET=/*&PUT=/*&POST=/*&DELETE=/*)
 */
$ovh = new Api('xxxxxxxxxx',  // Application Key
               'xxxxxxxxxx',  // Application Secret
               'ovh-eu',      // Endpoint of API OVH (List of available endpoints: https://github.com/ovh/python-ovh#2-configure-your-application)
               'xxxxxxxxxx'); // Consumer Key

$result = $ovh->get("/v2/publicCloud/project/{projectId}/compute/instance/{instanceId}/compatibleFlavor");

print_r($result);
?>
```

## Create an instance

`POST /v2/publicCloud/project/{projectId}/compute/instance`

Link: https://developers.eu.ovhcloud.com/reference/public-cloud/compute/instances/#createInstance

**Status:** Stable production version  
**IAM actions:** `publicCloudProject:apiovh:instance/create`, `publicCloudProject:apiovh:instance/usePublicIP`

### Create an instance

Provisions a new instance from the supplied `targetSpec`. Creation is asynchronous: the resource starts in `CREATING` and becomes `READY` once the backend has booted it. Poll `GET .../instance/{instanceId}` until `resourceStatus` is `READY` and `currentTasks` is empty.

### Create-time-only fields (immutable afterward)
Several fields can be set only at creation and can never be changed later:
* `location` — the region (and optional availability zone) the instance is deployed in.
* `sshKeyName` — the SSH key injected into the instance at boot.
* `group` — placement / instance-group membership. It binds the instance to an existing instance group (Nova server group) for `AFFINITY` / `ANTI_AFFINITY` scheduling. Server-group membership is fixed by OpenStack at boot and cannot be added, removed, or changed afterward — there is no group `PUT`.

### User data (cloud-init)
`targetSpec.userData` is a base64-encoded (strict standard encoding) cloud-init payload handed to the instance at boot through the OpenStack metadata service / config drive, and interpreted by cloud-init inside the guest image. The encoded string must be at most 65535 bytes. It is write-only: the value is never returned by `GET`/`LIST`. It is also not persisted or stored by the Public Cloud API: the payload is handed to the compute service, which makes it available to the instance via the metadata service. Only a non-reversible fingerprint of the value is retained, for change detection. Unlike the create-time-only fields above, `userData` can be changed later via `PUT`. See the `PUT` route for the destructive semantics of doing so.

### Declarative `volumes`
`targetSpec.volumes` is a declarative list of block-volume references attached to the instance. Supply the volumes to attach at boot. On a subsequent `PUT` the list is diffed to attach or detach volumes (see the `PUT` route). There is no imperative attach/detach endpoint.

### Declarative `shares`
`targetSpec.shares` is a declarative list of filesystem (Manila share) attachments. Each entry references a share plus an optional per-entry `accessLevel` (defaults to `READ_WRITE`). At creation, each attach creates a Manila IP access rule for the instance's interface on the share's network. The instance must have an interface on that network. As with volumes, the list is reconciled by diffing on `PUT`.

### Declarative `networks` and public IPs
`targetSpec.networks` is a declarative list of network interfaces. Each entry is `{id?, subnetId?, ip?, autoAssignPublicIp?}`, and the fields you set decide what it means:
* `{"autoAssignPublicIp": true}` — a public (Ext-Net) interface with a platform-assigned public IP. At most one entry may set it.
* `{"ip": "..."}` without a network `id` — a public IP the project already owns: either an existing additional IP (also known as a failover IP), or an Ext-Net IP of the project in the instance's region. Any other address is rejected. Such an entry implicitly attaches the public (Ext-Net) interface. Several are allowed, and they may coexist with an `autoAssignPublicIp` entry.
* `{"id": "...", "subnetId": "..."}` — a private interface whose fixed address is assigned by IPAM.
* `{"id": "...", "subnetId": "...", "ip": "..."}` — a private interface where `ip` pins the fixed address when it falls inside the subnet CIDR, and otherwise designates an existing floating IP to associate with that interface (the floating IP must already exist).

Any entry that sets `autoAssignPublicIp` or carries a public `ip` requires the optional `instance/usePublicIP` IAM action, including floating IP associations.

In `currentState.networks` the shape is different: there is one entry per network plus at most one id-less entry for the public (Ext-Net) interface, and every address is reported through that entry's `addresses` list. There is no scalar `ip`. Each address carries a `type`: `FIXED` for an address configured on the interface itself (a private fixed address, whether IPAM-assigned or pinned, and the Ext-Net address), `FLOATING` for a floating IP associated with the interface, and `ADDITIONAL` for an additional IP routed to the public interface (additional IPs no longer form their own entry). `autoAssignPublicIp` is never echoed back, because the backend cannot distinguish a platform-assigned address from a pinned one.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `projectId` | path | string | yes | Project ID |

### Request body (required)

Type: `publicCloud.instance.InstanceCreation`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `targetSpec` | publicCloud.instance.InstanceTargetSpec | yes | Desired specification. Full target specification of the instance to create. See InstanceTargetSpec for the per-field creation rules and immutability constraints. |
| `targetSpec.flavor` | publicCloud.instance.InstanceFlavorRef | yes | Reference to the flavor that sizes the instance (vCPUs, RAM, local disk). Carries only the flavor id. Changing the referenced flavor on PUT triggers a resize of the instance. |
| `targetSpec.flavor.id` | string (uuid) | yes | Identifier of the flavor to size the instance with. Changing it on update triggers a resize. |
| `targetSpec.group` | publicCloud.instance.InstanceGroupRef |  | Optional reference to the instance (placement) group the instance is created into, controlling affinity/anti-affinity placement. Immutable after creation. The group is set only at creation time. OpenStack/Nova server groups are immutable. There is no group change on PUT and membership cannot be changed after the instance exists. |
| `targetSpec.group.id` | string (uuid) | yes | Identifier of the instance group. Honored only at creation time. The group cannot be changed afterward. |
| `targetSpec.image` | publicCloud.instance.InstanceImageRef |  | Reference to the image the instance boots from. Carries only the image id. Changing the referenced image on PUT triggers a rebuild of the instance from the new image. |
| `targetSpec.image.id` | string (uuid) | yes | Identifier of the image to boot from. Changing it on update triggers a rebuild of the instance. |
| `targetSpec.location` | publicCloud.instance.InstanceLocation | yes | Target location. Region (and optional availability zone) where the instance is provisioned. Immutable after creation. An instance cannot be moved to another region/zone, which is why location is absent from InstanceUpdateTargetSpec. |
| `targetSpec.location.availabilityZone` | string |  | Availability zone within the region where the instance is placed. When omitted at creation the backend selects a zone automatically. Immutable after creation. |
| `targetSpec.location.region` | string | yes | Code of the region where the instance is provisioned, for example GRA11, BHS5. Immutable after creation. An instance cannot be moved to another region. |
| `targetSpec.name` | string | yes | Desired display name of the instance. Changing it on PUT triggers a rename. |
| `targetSpec.networks` | publicCloud.instance.InstanceNetworkRef[] |  | Declarative list of network interfaces the instance is attached to. An entry with a subnetId, and an optional id, is a private interface, optionally carrying an ip to pin its fixed address or to associate an existing floating IP. An entry with autoAssignPublicIp alone requests a public (Ext-Net) interface with a platform-assigned public IP. An entry with ip alone attaches a public IP the project already owns, either an additional IP or an Ext-Net IP of the project in the instance's region. See InstanceNetworkRef. The list drives the desired network topology: adding or removing an entry attaches or detaches the corresponding interface on update. |
| `targetSpec.networks[].autoAssignPublicIp` | boolean |  | Auto-assign public IP. Whether to attach a public (Ext-Net) interface with a public IP assigned by the platform. Only allowed on an entry that has no id, no subnetId and no ip, and at most one entry of the networks list may set it. Requires the optional instance/usePublicIP IAM action. |
| `targetSpec.networks[].id` | string (uuid) |  | Identifier of the private network to attach to. Optional on a private interface: when omitted, the network of subnetId is used. Omit it on an entry declaring public connectivity through autoAssignPublicIp or ip. |
| `targetSpec.networks[].ip` | ip |  | Address of this interface, whose meaning depends on the sibling fields. Without an id and a subnetId: a public IP the project already owns. An additional IP, or an Ext-Net IP of the project in the instance's region. Any other address is rejected, and the entry implicitly attaches the public (Ext-Net) interface. On a private entry (subnetId, with an optional id): pins the interface's fixed address when the address falls inside the subnet CIDR, and otherwise designates an EXISTING floating IP to associate with that interface. A public address requires the optional instance/usePublicIP IAM action. |
| `targetSpec.networks[].subnetId` | string (uuid) |  | Identifier of the subnet the interface draws its fixed address from. Required for a private interface. Leave unset on an entry declaring public connectivity. |
| `targetSpec.powerState` | publicCloud.instance.PowerStateEnum |  | Desired administrative power state of the instance (see PowerStateEnum: ACTIVE, PAUSED, RESCUE, SHELVED, SHUTOFF, SUSPENDED). Changing it on PUT drives the corresponding power transition (start, stop, shelve, rescue, pause, suspend). Defaults to ACTIVE. — one of `ACTIVE`, `PAUSED`, `RESCUE`, `SHELVED`, `SHUTOFF`, `SUSPENDED` |
| `targetSpec.securityGroups` | publicCloud.securityGroup.SecurityGroupRef[] |  | Optional list of references to the security groups applied to all of the instance's ports. Each entry carries the security group id. Changing this list on PUT re-applies the resulting set of security groups to every instance port. |
| `targetSpec.securityGroups[].id` | string (uuid) | yes | Identifier of the security group |
| `targetSpec.shares` | publicCloud.instance.InstanceShareRef[] |  | Declarative list of file storage (shares) attached to the instance, managed exactly like volumes: the diff of this list on PUT drives attach/detach. Attaching a share creates a Manila IP access rule for the instance's interface on the share's network. The instance must have an interface on that network or the operation errors. Detaching (removing an entry from this list) deletes the matching access rule and is idempotent. Each entry's accessLevel defaults to READ_WRITE when omitted (see InstanceShareRef). |
| `targetSpec.shares[].accessLevel` | publicCloud.storage.file.FileStorageAccessLevelEnum |  | Desired access level granted to the instance for this share (see FileStorageAccessLevelEnum: READ_ONLY, READ_WRITE). Defaults to READ_WRITE. — one of `READ_ONLY`, `READ_WRITE` |
| `targetSpec.shares[].id` | string (uuid) | yes | Identifier of the file storage (share) to attach. Adding this reference attaches the share to the instance. Removing it from the shares list detaches it. |
| `targetSpec.sshKeyName` | string |  | Name of the SSH key pair injected into the instance at boot for initial access. Immutable after creation. The key is injected once during provisioning and cannot be changed afterward, which is why sshKeyName is absent from InstanceUpdateTargetSpec. |
| `targetSpec.userData` | string |  | User data (cloud-init). Base64-encoded (strict standard encoding) cloud-init payload handed to the instance at boot through the OpenStack metadata service / config drive, and interpreted by cloud-init inside the guest image. The submitted string itself must be at most 65535 bytes once base64-encoded. Write-only: never returned by GET/LIST. Deliberately absent from InstanceReadTargetSpec and InstanceCurrentState. Not persisted or stored by the Public Cloud API: the payload is handed to the compute service, which makes it available to the instance via the metadata service. Only a non-reversible fingerprint of the value is retained, for change detection. Mutable, but destructively: changing userData on PUT REINSTALLS the instance (a Nova rebuild on the current image), wiping the root disk and all data on it. See InstanceUpdateTargetSpec for the tri-state update semantics. |
| `targetSpec.volumes` | publicCloud.instance.InstanceVolumeRef[] |  | Declarative list of block volumes attached to the instance, each referencing a volume by id (see InstanceVolumeRef). Attach/detach is driven by diffing this list on PUT. There is no imperative attach/detach sub-route. Adding a volume reference attaches that volume. Removing one detaches it. |
| `targetSpec.volumes[].id` | string (uuid) | yes | Identifier of the volume to attach. Adding this reference attaches the volume. Removing it from the volumes list detaches it. |

```json
{
  "targetSpec": {
    "flavor": {
      "id": "00000000-0000-0000-0000-000000000000"
    },
    "group": {
      "id": "00000000-0000-0000-0000-000000000000"
    },
    "image": {
      "id": "00000000-0000-0000-0000-000000000000"
    },
    "location": {
      "availabilityZone": "string",
      "region": "string"
    },
    "name": "string",
    "networks": [
      {
        "autoAssignPublicIp": true,
        "id": "00000000-0000-0000-0000-000000000000",
        "ip": "192.0.2.0",
        "subnetId": "00000000-0000-0000-0000-000000000000"
      }
    ],
    "powerState": "ACTIVE",
    "securityGroups": [
      {
        "id": "00000000-0000-0000-0000-000000000000"
      }
    ],
    "shares": [
      {
        "accessLevel": "READ_ONLY",
        "id": "00000000-0000-0000-0000-000000000000"
      }
    ],
    "sshKeyName": "string",
    "userData": "string",
    "volumes": [
      {
        "id": "00000000-0000-0000-0000-000000000000"
      }
    ]
  }
}
```

### Responses

| Status | Type | Description |
| --- | --- | --- |
| 200 | publicCloud.instance.Instance | successful operation |
| 400 | object | Error 400 response |
| 409 | object | Error 409 response |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `checksum` | string | read-only | Computed hash representing the current targetSpec value. It enables optional optimistic concurrency control: the value returned by a GET may be sent back in the PUT and action payloads, and the request is then rejected with a 409 checksum-mismatch conflict if it no longer matches server-side (because another request modified the instance in the meantime). Sending no checksum skips that check and forces the write (last-write-wins). |
| `createdAt` | string (date-time) | read-only | Creation date of the instance, as an ISO 8601 / RFC 3339 timestamp |
| `currentState` | publicCloud.instance.InstanceCurrentState | read-only | Current observed state of the instance as reported by the compute backend (name, flavor, image, location, power state, networks, attached volumes, attached shares, security groups). It is null while the instance is still being created and no backend state is available yet. |
| `currentState.availableActions` | publicCloud.instance.InstanceAvailableAction[] | read-only | Availability of every instance action type given the current state of the instance. Always contains exactly one entry per InstanceActionTypeEnum value, in the order of that enum, each flagged with whether it can currently be triggered through the action endpoint. For example, when the instance is locked only UNLOCK is available. While a task is in progress on the instance or when it is in error, none is available. |
| `currentState.availableActions[].available` | boolean | read-only | Whether the action can currently be triggered through the action endpoint. A call with an unavailable action is refused. |
| `currentState.availableActions[].name` | publicCloud.instance.InstanceActionTypeEnum | read-only | Action type, as accepted by the action endpoint — one of `LOCK`, `PAUSE`, `REBOOT`, `RESCUE`, `RESUME`, `SHELVE`, `START`, `STOP`, `SUSPEND`, `UNLOCK`, `UNPAUSE`, `UNRESCUE`, … |
| `currentState.flavor` | publicCloud.instance.InstanceFlavor | read-only | Observed flavor of the instance with full details (name, vCPUs, RAM, local disk). See InstanceFlavor. |
| `currentState.flavor.bandwidth` | publicCloud.instance.FlavorBandwidth | read-only | Network bandwidth of the flavor in Mbit/s. Null when the flavor is not in the catalog. |
| `currentState.flavor.disk` | integer | read-only | Size of the flavor's local root disk in GB |
| `currentState.flavor.gpus` | integer | read-only | Number of physical GPUs provided by the flavor, 0 for flavors without GPU |
| `currentState.flavor.id` | string (uuid) | read-only | Unique identifier of the flavor |
| `currentState.flavor.name` | string | read-only | Human-readable flavor name, for example the commercial flavor label |
| `currentState.flavor.ram` | integer | read-only | Amount of RAM provided by the flavor in MB |
| `currentState.flavor.vcpus` | integer | read-only | Number of virtual CPUs provided by the flavor |
| `currentState.group` | publicCloud.instance.InstanceGroupRef | read-only | Reference to the instance (placement) group the instance belongs to. Null when it is not part of any group. Immutable after creation. |
| `currentState.group.id` | string (uuid) | yes | Identifier of the instance group. Honored only at creation time. The group cannot be changed afterward. |
| `currentState.hostId` | string | read-only | Opaque identifier of the physical host the instance is running on, as exposed by OpenStack. Null when not available. |
| `currentState.image` | publicCloud.instance.InstanceImage | read-only | Observed image the instance was booted from, with full details (name, size, status). Null for boot-from-volume instances, which have no image. See InstanceImage. |
| `currentState.image.defaultUser` | string | read-only | Default login user of the image, as set by its publisher, for example almalinux or ubuntu. Null when the image declares none. |
| `currentState.image.deprecated` | boolean | read-only | Whether the image is flagged as deprecated. A deprecated image can still boot existing instances but is no longer recommended for new ones. |
| `currentState.image.id` | string (uuid) | read-only | Unique identifier of the image |
| `currentState.image.name` | string | read-only | Human-readable image name. Null when not reported by the backend. |
| `currentState.image.size` | integer | read-only | Size of the image in bytes. Null when the backend does not report it. |
| `currentState.image.status` | publicCloud.instance.ImageStatusEnum | read-only | Lifecycle status of the image as reported by Glance (see ImageStatusEnum). Null when not reported. — one of `ACTIVE`, `DEACTIVATED`, `DELETED`, `IMPORTING`, `KILLED`, `PENDING_DELETE`, `QUEUED`, `SAVING` |
| `currentState.location` | publicCloud.instance.InstanceLocation | read-only | Location. Observed region and availability zone where the instance is provisioned. See InstanceLocation. |
| `currentState.location.availabilityZone` | string |  | Availability zone within the region where the instance is placed. When omitted at creation the backend selects a zone automatically. Immutable after creation. |
| `currentState.location.region` | string | yes | Code of the region where the instance is provisioned, for example GRA11, BHS5. Immutable after creation. An instance cannot be moved to another region. |
| `currentState.locked` | boolean | read-only | Lock state. Whether the instance is locked against modifications. When locked, mutating actions are refused until it is unlocked (see the LOCK/UNLOCK actions in InstanceActionTypeEnum). |
| `currentState.name` | string | read-only | Observed display name of the instance |
| `currentState.networks` | publicCloud.instance.InstanceNetwork[] | read-only | Observed network interfaces of the instance, with full details (network, subnet, gateway and per-interface addresses). One entry per network, plus at most one entry without an id for the public (Ext-Net) interface. Every address of the instance is reported through the entry's addresses list, each address typed FIXED, FLOATING or ADDITIONAL. There is no separate scalar address field. See InstanceNetwork. |
| `currentState.networks[].addresses` | publicCloud.instance.InstanceNetworkAddress[] | read-only | Every IP address through which the instance is reachable on this interface, each with its type, IP version and MAC address. It carries the interface's fixed addresses and, where applicable, the floating IP associated with it and any additional IPs routed to it. This is the single source of truth for the instance's observed addresses. Null or empty only while no address has been assigned yet. See InstanceNetworkAddress. |
| `currentState.networks[].gatewayId` | string (uuid) | read-only | Identifier of the gateway providing egress for this interface. Null when none applies. |
| `currentState.networks[].id` | string (uuid) | read-only | Identifier of the network this interface is attached to, or null for the public (Ext-Net) interface. There is at most one entry without an id: additional IPs are reported as ADDITIONAL addresses of that public entry instead of forming their own entry. |
| `currentState.networks[].subnetId` | string (uuid) | read-only | Identifier of the subnet this interface draws its fixed address from, or null for an entry without a network id |
| `currentState.powerState` | publicCloud.instance.PowerStateEnum | read-only | Actual administrative power state of the instance as reported by OpenStack (see PowerStateEnum). This may transiently differ from targetSpec.powerState while a power transition is in progress. — one of `ACTIVE`, `PAUSED`, `RESCUE`, `SHELVED`, `SHUTOFF`, `SUSPENDED` |
| `currentState.projectId` | string | read-only | Identifier of the Public Cloud project the instance belongs to |
| `currentState.securityGroups` | publicCloud.securityGroup.SecurityGroupRef[] | read-only | References to the security groups currently attached to the instance's ports |
| `currentState.securityGroups[].id` | string (uuid) | yes | Identifier of the security group |
| `currentState.shares` | publicCloud.instance.InstanceShare[] | read-only | Observed instance-side share attachments. Only populated on a GET of a single instance (never in list responses). Mixing per-share access rules (managed directly on the share resource) with instance-side attach on the same share is unsupported and will show the share OUT_OF_SYNC. See InstanceShare. |
| `currentState.shares[].accessLevel` | publicCloud.storage.file.FileStorageAccessLevelEnum | read-only | Observed access level of the access rule for this instance (see FileStorageAccessLevelEnum: READ_ONLY, READ_WRITE) — one of `READ_ONLY`, `READ_WRITE` |
| `currentState.shares[].accessTo` | string | read-only | The instance IP address the Manila access rule targets. The instance's fixed IPv4 address on the share's network. |
| `currentState.shares[].id` | string (uuid) | read-only | Identifier of the attached file storage (share) |
| `currentState.shares[].state` | publicCloud.storage.file.FileStorageAccessRuleStateEnum | read-only | Observed state of the underlying access rule (see FileStorageAccessRuleStateEnum: ACTIVE, APPLYING, DENYING, ERROR). Null while no state has been reported yet. — one of `ACTIVE`, `APPLYING`, `DENYING`, `ERROR` |
| `currentState.sshKeyName` | string | read-only | Name of the SSH key pair injected into the instance at boot. Null when none was provided. |
| `currentState.userId` | string | read-only | Identifier of the OpenStack user that owns the instance |
| `currentState.volumes` | publicCloud.instance.InstanceVolume[] | read-only | Observed block volumes attached to the instance, with details (name, size). See InstanceVolume. |
| `currentState.volumes[].id` | string (uuid) | read-only | Unique identifier of the attached volume |
| `currentState.volumes[].name` | string | read-only | Display name of the attached volume |
| `currentState.volumes[].size` | integer | read-only | Size of the attached volume in GB |
| `currentTasks` | common.CurrentTask[] | read-only | In-progress operations. Ongoing asynchronous tasks reconciling currentState toward targetSpec, for example a create, resize, reboot, volume attach or share attach. Poll the instance until this list is empty and resourceStatus is READY to know the requested change has been applied. |
| `currentTasks[].errors` | common.TaskError[] | read-only | Errors that occurred on the task |
| `currentTasks[].errors[].message` | string | read-only | Error description |
| `currentTasks[].id` | string (uuid) | read-only | Identifier of the current task |
| `currentTasks[].link` | string | read-only | Link to the task details |
| `currentTasks[].status` | common.CurrentTaskStatusEnum | read-only | Current global status of the current task — one of `ERROR`, `PENDING`, `RUNNING`, `SCHEDULED`, `WAITING_USER_INPUT` |
| `currentTasks[].type` | string | read-only | Type of the current task |
| `id` | string (uuid) | read-only | Unique identifier of the instance |
| `resourceStatus` | common.ResourceStatusEnum | read-only | Resource lifecycle status. High-level readiness of the instance in the system, for example CREATING, READY, UPDATING, DELETING, ERROR. This is distinct from currentState.powerState, which carries the lower-level OpenStack administrative power state of the virtual machine. — one of `CREATING`, `CREATION_PLANNED`, `DELETING`, `ERROR`, `OUT_OF_SYNC`, `READY`, `SUSPENDED`, `UNKNOWN`, `UPDATING` |
| `targetSpec` | publicCloud.instance.InstanceReadTargetSpec | read-only | Desired specification. Last target specification requested for the instance. On update, the difference between the previous and the new targetSpec determines the operations performed (rename, resize, power change, and declarative volume/share attach-detach). |
| `targetSpec.flavor` | publicCloud.instance.InstanceFlavorRef | read-only | Reference to the flavor that sizes the instance (vCPUs, RAM, local disk). Carries only the flavor id. Changing the referenced flavor on PUT triggers a resize of the instance. |
| `targetSpec.flavor.id` | string (uuid) | yes | Identifier of the flavor to size the instance with. Changing it on update triggers a resize. |
| `targetSpec.group` | publicCloud.instance.InstanceGroupRef | read-only | Optional reference to the instance (placement) group the instance is created into, controlling affinity/anti-affinity placement. Immutable: the group is set only at creation time. OpenStack/Nova server groups are immutable. There is no group change on PUT and membership cannot be changed after the instance exists. |
| `targetSpec.group.id` | string (uuid) | yes | Identifier of the instance group. Honored only at creation time. The group cannot be changed afterward. |
| `targetSpec.image` | publicCloud.instance.InstanceImageRef | read-only | Reference to the image the instance boots from. Carries only the image id. Changing the referenced image on PUT triggers a rebuild of the instance from the new image. Null for boot-from-volume instances, which have no backing image. |
| `targetSpec.image.id` | string (uuid) | yes | Identifier of the image to boot from. Changing it on update triggers a rebuild of the instance. |
| `targetSpec.location` | publicCloud.instance.InstanceLocation | read-only | Target location. Region (and optional availability zone) where the instance is provisioned. Immutable after creation. An instance cannot be moved to another region/zone, which is why location is absent from InstanceUpdateTargetSpec. |
| `targetSpec.location.availabilityZone` | string |  | Availability zone within the region where the instance is placed. When omitted at creation the backend selects a zone automatically. Immutable after creation. |
| `targetSpec.location.region` | string | yes | Code of the region where the instance is provisioned, for example GRA11, BHS5. Immutable after creation. An instance cannot be moved to another region. |
| `targetSpec.name` | string | read-only | Desired display name of the instance. Changing it on PUT triggers a rename. |
| `targetSpec.networks` | publicCloud.instance.InstanceNetworkRef[] | read-only | Declarative list of network interfaces the instance is attached to. An entry with a subnetId, and an optional id, is a private interface, optionally carrying an ip to pin its fixed address or to associate an existing floating IP. An entry with autoAssignPublicIp alone requests a public (Ext-Net) interface with a platform-assigned public IP. An entry with ip alone attaches a public IP the project already owns, either an additional IP or an Ext-Net IP of the project in the instance's region. See InstanceNetworkRef. The list drives the desired network topology: adding or removing an entry attaches or detaches the corresponding interface on update. |
| `targetSpec.networks[].autoAssignPublicIp` | boolean |  | Auto-assign public IP. Whether to attach a public (Ext-Net) interface with a public IP assigned by the platform. Only allowed on an entry that has no id, no subnetId and no ip, and at most one entry of the networks list may set it. Requires the optional instance/usePublicIP IAM action. |
| `targetSpec.networks[].id` | string (uuid) |  | Identifier of the private network to attach to. Optional on a private interface: when omitted, the network of subnetId is used. Omit it on an entry declaring public connectivity through autoAssignPublicIp or ip. |
| `targetSpec.networks[].ip` | ip |  | Address of this interface, whose meaning depends on the sibling fields. Without an id and a subnetId: a public IP the project already owns. An additional IP, or an Ext-Net IP of the project in the instance's region. Any other address is rejected, and the entry implicitly attaches the public (Ext-Net) interface. On a private entry (subnetId, with an optional id): pins the interface's fixed address when the address falls inside the subnet CIDR, and otherwise designates an EXISTING floating IP to associate with that interface. A public address requires the optional instance/usePublicIP IAM action. |
| `targetSpec.networks[].subnetId` | string (uuid) |  | Identifier of the subnet the interface draws its fixed address from. Required for a private interface. Leave unset on an entry declaring public connectivity. |
| `targetSpec.powerState` | publicCloud.instance.PowerStateEnum | read-only | Desired administrative power state of the instance (see PowerStateEnum: ACTIVE, PAUSED, RESCUE, SHELVED, SHUTOFF, SUSPENDED). Changing it on PUT drives the corresponding power transition (start, stop, shelve, rescue, pause, suspend). Defaults to ACTIVE. — one of `ACTIVE`, `PAUSED`, `RESCUE`, `SHELVED`, `SHUTOFF`, `SUSPENDED` |
| `targetSpec.securityGroups` | publicCloud.securityGroup.SecurityGroupRef[] | read-only | Optional list of references to the security groups applied to all of the instance's ports. Each entry carries the security group id. Changing this list on PUT re-applies the resulting set of security groups to every instance port. |
| `targetSpec.securityGroups[].id` | string (uuid) | yes | Identifier of the security group |
| `targetSpec.shares` | publicCloud.instance.InstanceShareRef[] | read-only | Declarative list of file storage (shares) attached to the instance, managed exactly like volumes: the diff of this list on PUT drives attach/detach. Attaching a share creates a Manila IP access rule for the instance's interface on the share's network. The instance must have an interface on that network or the operation errors. Detaching (removing an entry from this list) deletes the matching access rule and is idempotent. Each entry's accessLevel defaults to READ_WRITE when omitted (see InstanceShareRef). |
| `targetSpec.shares[].accessLevel` | publicCloud.storage.file.FileStorageAccessLevelEnum |  | Desired access level granted to the instance for this share (see FileStorageAccessLevelEnum: READ_ONLY, READ_WRITE). Defaults to READ_WRITE. — one of `READ_ONLY`, `READ_WRITE` |
| `targetSpec.shares[].id` | string (uuid) | yes | Identifier of the file storage (share) to attach. Adding this reference attaches the share to the instance. Removing it from the shares list detaches it. |
| `targetSpec.sshKeyName` | string | read-only | Name of the SSH key pair injected into the instance at boot for initial access. Immutable / create-only: the key is injected once during provisioning and cannot be changed afterward, which is why sshKeyName is absent from InstanceUpdateTargetSpec. |
| `targetSpec.volumes` | publicCloud.instance.InstanceVolumeRef[] | read-only | Declarative list of block volumes attached to the instance, each referencing a volume by id (see InstanceVolumeRef). Attach/detach is driven by diffing this list on PUT. There is no imperative attach/detach sub-route. Adding a volume reference attaches that volume. Removing one detaches it. |
| `targetSpec.volumes[].id` | string (uuid) | yes | Identifier of the volume to attach. Adding this reference attaches the volume. Removing it from the volumes list detaches it. |
| `updatedAt` | string (date-time) | read-only | Last modification date of the instance, as an ISO 8601 / RFC 3339 timestamp |

```json
{
  "checksum": "string",
  "createdAt": "2024-01-01T12:00:00Z",
  "currentState": {
    "availableActions": [
      {
        "available": true,
        "name": "LOCK"
      }
    ],
    "flavor": {
      "bandwidth": {
        "private": 0,
        "publicInbound": 0,
        "publicOutbound": 0
      },
      "disk": 0,
      "gpus": 0,
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "string",
      "ram": 0,
      "vcpus": 0
    },
    "group": {
      "id": "00000000-0000-0000-0000-000000000000"
    },
    "hostId": "string",
    "image": {
      "defaultUser": "string",
      "deprecated": true,
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "string",
      "size": 0,
      "status": "ACTIVE"
    },
    "location": {
      "availabilityZone": "string",
      "region": "string"
    },
    "locked": true,
    "name": "string",
    "networks": [
      {
        "addresses": [
          {
            "ip": "192.0.2.0",
            "mac": "00:00:5e:00:53:01",
            "type": "ADDITIONAL",
            "version": 0
          }
        ],
        "gatewayId": "00000000-0000-0000-0000-000000000000",
        "id": "00000000-0000-0000-0000-000000000000",
        "subnetId": "00000000-0000-0000-0000-000000000000"
      }
    ],
    "powerState": "ACTIVE",
    "projectId": "string",
    "securityGroups": [
      {
        "id": "00000000-0000-0000-0000-000000000000"
      }
    ],
    "shares": [
      {
        "accessLevel": "READ_ONLY",
        "accessTo": "string",
        "id": "00000000-0000-0000-0000-000000000000",
  …
```

### Example

```bash
curl -X POST \
  "https://api.eu.ovhcloud.com/v2/publicCloud/project/{projectId}/compute/instance" \
  -H "accept: application/json" \
  -H "authorization: Bearer $OVH_TOKEN" \
  -H "content-type: application/json" \
  -d '{ }'
```

```python
'''
First, install the latest release of Python wrapper: $ pip install ovh
'''
import json
import ovh

# Instantiate an OVH Client.
# You can generate new credentials with full access to your account on
# the token creation page (https://api.ovh.com/createToken/index.cgi?GET=/*&PUT=/*&POST=/*&DELETE=/*)
client = ovh.Client(
	endpoint='ovh-eu',               # Endpoint of API OVH (List of available endpoints: https://github.com/ovh/python-ovh#2-configure-your-application)
	application_key='xxxxxxxxxx',    # Application Key
	application_secret='xxxxxxxxxx', # Application Secret
	consumer_key='xxxxxxxxxx',       # Consumer Key
)

# Request body type: publicCloud.instance.InstanceCreation
result = client.post("/v2/publicCloud/project/{projectId}/compute/instance",
	targetSpec = None, # Desired specification. Full target specification of the instance to create. See InstanceTargetSpec for the per-field creation rules and immutability constraints. (type: publicCloud.instance.InstanceTargetSpec)
)

# Pretty print
print(json.dumps(result, indent=4))
```

```php
<?php
/**
 * First, download the latest release of PHP wrapper on github
 * And include this script into the folder with extracted files
 */
require __DIR__ . '/vendor/autoload.php';
use \Ovh\Api;

/**
 * Instantiate an OVH Client.
 * You can generate new credentials with full access to your account on
 * the token creation page (https://api.ovh.com/createToken/index.cgi?GET=/*&PUT=/*&POST=/*&DELETE=/*)
 */
$ovh = new Api('xxxxxxxxxx',  // Application Key
               'xxxxxxxxxx',  // Application Secret
               'ovh-eu',      // Endpoint of API OVH (List of available endpoints: https://github.com/ovh/python-ovh#2-configure-your-application)
               'xxxxxxxxxx'); // Consumer Key

// Request body type: publicCloud.instance.InstanceCreation
$result = $ovh->post("/v2/publicCloud/project/{projectId}/compute/instance", array(
	targetSpec => null, // Desired specification. Full target specification of the instance to create. See InstanceTargetSpec for the per-field creation rules and immutability constraints. (type: publicCloud.instance.InstanceTargetSpec)
));

print_r($result);
?>
```

## Run an instance action

`POST /v2/publicCloud/project/{projectId}/compute/instance/{instanceId}/action`

Link: https://developers.eu.ovhcloud.com/reference/public-cloud/compute/instances/#postInstanceAction

**Status:** Stable production version  
**IAM actions:** `publicCloudProject:apiovh:instance/runAction`

### Perform an instance action

Imperative endpoint for power and lifecycle actions on an instance. This is the one place such imperative operations live. Distinct from the declarative `PUT` on the instance, which reconciles desired state from a `targetSpec` diff. Actions are asynchronous: the instance transitions through the relevant transient state and the response echoes the instance. Poll `GET .../instance/{instanceId}` until `resourceStatus` is `READY` and `currentTasks` is empty.

### Action `type`
The `type` field selects the operation:
* `REBOOT` — reboot the instance (`parameters.hard` chooses a hard vs. soft reboot).
* `START` / `STOP` — power the instance on / off.
* `SHELVE` / `UNSHELVE` — shelve the instance (freeing hypervisor resources) and restore it.
* `PAUSE` / `UNPAUSE` — freeze a running instance in the memory of the host, and unfreeze it.
* `SUSPEND` / `RESUME` — save the memory state of a running instance to disk and stop it, and restore it.
* `RESCUE` / `UNRESCUE` — boot into rescue mode (optionally from `parameters.imageId`) and return to normal boot.
* `LOCK` / `UNLOCK` — lock the instance against accidental actions / modifications, and unlock it.

### Optimistic concurrency (`checksum`)
The `checksum` is optional. When you send it, it must match the current server-side value or the action is rejected with a checksum-mismatch error. Re-`GET` and retry. When you omit it (or send an empty string), the check is skipped and the action is forced (last-write-wins). An action requested while the instance is in an incompatible state is rejected with `ResourceInInvalidState`.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `instanceId` | path | string (uuid) | yes | Instance ID |
| `projectId` | path | string | yes | Project ID |

### Request body (required)

Type: `publicCloud.instance.InstanceActionRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `checksum` | string |  | Concurrency-control checksum. Optional checksum obtained from the last GET of the instance. When supplied, it must still match the instance's current checksum or the action is rejected with a 409 checksum-mismatch conflict, protecting against a concurrent modification. When omitted or empty, the concurrency check is skipped and the action is forced (last-write-wins). |
| `parameters` | publicCloud.instance.InstanceActionParameters |  | Optional parameters refining the requested action (see InstanceActionParameters). Only relevant for actions that accept options, such as a hard REBOOT or a RESCUE with a specific image. Omit for actions that take none. |
| `parameters.hard` | boolean |  | Applies only to the REBOOT action. When true, performs a hard reboot (power cycle) instead of a graceful, soft reboot. Defaults to a soft reboot. |
| `parameters.imageId` | string |  | Applies only to the RESCUE action. Identifier of the image to boot the instance from while in rescue mode. When omitted, the backend selects a default rescue image. |
| `type` | publicCloud.instance.InstanceActionTypeEnum | yes | Action type. The imperative action to perform on the instance (see InstanceActionTypeEnum: LOCK, UNLOCK, REBOOT, RESCUE, UNRESCUE, STOP, START, SHELVE, UNSHELVE, PAUSE, UNPAUSE, SUSPEND, RESUME). — one of `LOCK`, `PAUSE`, `REBOOT`, `RESCUE`, `RESUME`, `SHELVE`, `START`, `STOP`, `SUSPEND`, `UNLOCK`, `UNPAUSE`, `UNRESCUE`, … |

```json
{
  "checksum": "string",
  "parameters": {
    "hard": true,
    "imageId": "string"
  },
  "type": "LOCK"
}
```

### Responses

| Status | Type | Description |
| --- | --- | --- |
| 200 | publicCloud.instance.Instance | successful operation |
| 400 | object | Error 400 response |
| 404 | object | Error 404 response |
| 409 | object | Error 409 response |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `checksum` | string | read-only | Computed hash representing the current targetSpec value. It enables optional optimistic concurrency control: the value returned by a GET may be sent back in the PUT and action payloads, and the request is then rejected with a 409 checksum-mismatch conflict if it no longer matches server-side (because another request modified the instance in the meantime). Sending no checksum skips that check and forces the write (last-write-wins). |
| `createdAt` | string (date-time) | read-only | Creation date of the instance, as an ISO 8601 / RFC 3339 timestamp |
| `currentState` | publicCloud.instance.InstanceCurrentState | read-only | Current observed state of the instance as reported by the compute backend (name, flavor, image, location, power state, networks, attached volumes, attached shares, security groups). It is null while the instance is still being created and no backend state is available yet. |
| `currentState.availableActions` | publicCloud.instance.InstanceAvailableAction[] | read-only | Availability of every instance action type given the current state of the instance. Always contains exactly one entry per InstanceActionTypeEnum value, in the order of that enum, each flagged with whether it can currently be triggered through the action endpoint. For example, when the instance is locked only UNLOCK is available. While a task is in progress on the instance or when it is in error, none is available. |
| `currentState.availableActions[].available` | boolean | read-only | Whether the action can currently be triggered through the action endpoint. A call with an unavailable action is refused. |
| `currentState.availableActions[].name` | publicCloud.instance.InstanceActionTypeEnum | read-only | Action type, as accepted by the action endpoint — one of `LOCK`, `PAUSE`, `REBOOT`, `RESCUE`, `RESUME`, `SHELVE`, `START`, `STOP`, `SUSPEND`, `UNLOCK`, `UNPAUSE`, `UNRESCUE`, … |
| `currentState.flavor` | publicCloud.instance.InstanceFlavor | read-only | Observed flavor of the instance with full details (name, vCPUs, RAM, local disk). See InstanceFlavor. |
| `currentState.flavor.bandwidth` | publicCloud.instance.FlavorBandwidth | read-only | Network bandwidth of the flavor in Mbit/s. Null when the flavor is not in the catalog. |
| `currentState.flavor.disk` | integer | read-only | Size of the flavor's local root disk in GB |
| `currentState.flavor.gpus` | integer | read-only | Number of physical GPUs provided by the flavor, 0 for flavors without GPU |
| `currentState.flavor.id` | string (uuid) | read-only | Unique identifier of the flavor |
| `currentState.flavor.name` | string | read-only | Human-readable flavor name, for example the commercial flavor label |
| `currentState.flavor.ram` | integer | read-only | Amount of RAM provided by the flavor in MB |
| `currentState.flavor.vcpus` | integer | read-only | Number of virtual CPUs provided by the flavor |
| `currentState.group` | publicCloud.instance.InstanceGroupRef | read-only | Reference to the instance (placement) group the instance belongs to. Null when it is not part of any group. Immutable after creation. |
| `currentState.group.id` | string (uuid) | yes | Identifier of the instance group. Honored only at creation time. The group cannot be changed afterward. |
| `currentState.hostId` | string | read-only | Opaque identifier of the physical host the instance is running on, as exposed by OpenStack. Null when not available. |
| `currentState.image` | publicCloud.instance.InstanceImage | read-only | Observed image the instance was booted from, with full details (name, size, status). Null for boot-from-volume instances, which have no image. See InstanceImage. |
| `currentState.image.defaultUser` | string | read-only | Default login user of the image, as set by its publisher, for example almalinux or ubuntu. Null when the image declares none. |
| `currentState.image.deprecated` | boolean | read-only | Whether the image is flagged as deprecated. A deprecated image can still boot existing instances but is no longer recommended for new ones. |
| `currentState.image.id` | string (uuid) | read-only | Unique identifier of the image |
| `currentState.image.name` | string | read-only | Human-readable image name. Null when not reported by the backend. |
| `currentState.image.size` | integer | read-only | Size of the image in bytes. Null when the backend does not report it. |
| `currentState.image.status` | publicCloud.instance.ImageStatusEnum | read-only | Lifecycle status of the image as reported by Glance (see ImageStatusEnum). Null when not reported. — one of `ACTIVE`, `DEACTIVATED`, `DELETED`, `IMPORTING`, `KILLED`, `PENDING_DELETE`, `QUEUED`, `SAVING` |
| `currentState.location` | publicCloud.instance.InstanceLocation | read-only | Location. Observed region and availability zone where the instance is provisioned. See InstanceLocation. |
| `currentState.location.availabilityZone` | string |  | Availability zone within the region where the instance is placed. When omitted at creation the backend selects a zone automatically. Immutable after creation. |
| `currentState.location.region` | string | yes | Code of the region where the instance is provisioned, for example GRA11, BHS5. Immutable after creation. An instance cannot be moved to another region. |
| `currentState.locked` | boolean | read-only | Lock state. Whether the instance is locked against modifications. When locked, mutating actions are refused until it is unlocked (see the LOCK/UNLOCK actions in InstanceActionTypeEnum). |
| `currentState.name` | string | read-only | Observed display name of the instance |
| `currentState.networks` | publicCloud.instance.InstanceNetwork[] | read-only | Observed network interfaces of the instance, with full details (network, subnet, gateway and per-interface addresses). One entry per network, plus at most one entry without an id for the public (Ext-Net) interface. Every address of the instance is reported through the entry's addresses list, each address typed FIXED, FLOATING or ADDITIONAL. There is no separate scalar address field. See InstanceNetwork. |
| `currentState.networks[].addresses` | publicCloud.instance.InstanceNetworkAddress[] | read-only | Every IP address through which the instance is reachable on this interface, each with its type, IP version and MAC address. It carries the interface's fixed addresses and, where applicable, the floating IP associated with it and any additional IPs routed to it. This is the single source of truth for the instance's observed addresses. Null or empty only while no address has been assigned yet. See InstanceNetworkAddress. |
| `currentState.networks[].gatewayId` | string (uuid) | read-only | Identifier of the gateway providing egress for this interface. Null when none applies. |
| `currentState.networks[].id` | string (uuid) | read-only | Identifier of the network this interface is attached to, or null for the public (Ext-Net) interface. There is at most one entry without an id: additional IPs are reported as ADDITIONAL addresses of that public entry instead of forming their own entry. |
| `currentState.networks[].subnetId` | string (uuid) | read-only | Identifier of the subnet this interface draws its fixed address from, or null for an entry without a network id |
| `currentState.powerState` | publicCloud.instance.PowerStateEnum | read-only | Actual administrative power state of the instance as reported by OpenStack (see PowerStateEnum). This may transiently differ from targetSpec.powerState while a power transition is in progress. — one of `ACTIVE`, `PAUSED`, `RESCUE`, `SHELVED`, `SHUTOFF`, `SUSPENDED` |
| `currentState.projectId` | string | read-only | Identifier of the Public Cloud project the instance belongs to |
| `currentState.securityGroups` | publicCloud.securityGroup.SecurityGroupRef[] | read-only | References to the security groups currently attached to the instance's ports |
| `currentState.securityGroups[].id` | string (uuid) | yes | Identifier of the security group |
| `currentState.shares` | publicCloud.instance.InstanceShare[] | read-only | Observed instance-side share attachments. Only populated on a GET of a single instance (never in list responses). Mixing per-share access rules (managed directly on the share resource) with instance-side attach on the same share is unsupported and will show the share OUT_OF_SYNC. See InstanceShare. |
| `currentState.shares[].accessLevel` | publicCloud.storage.file.FileStorageAccessLevelEnum | read-only | Observed access level of the access rule for this instance (see FileStorageAccessLevelEnum: READ_ONLY, READ_WRITE) — one of `READ_ONLY`, `READ_WRITE` |
| `currentState.shares[].accessTo` | string | read-only | The instance IP address the Manila access rule targets. The instance's fixed IPv4 address on the share's network. |
| `currentState.shares[].id` | string (uuid) | read-only | Identifier of the attached file storage (share) |
| `currentState.shares[].state` | publicCloud.storage.file.FileStorageAccessRuleStateEnum | read-only | Observed state of the underlying access rule (see FileStorageAccessRuleStateEnum: ACTIVE, APPLYING, DENYING, ERROR). Null while no state has been reported yet. — one of `ACTIVE`, `APPLYING`, `DENYING`, `ERROR` |
| `currentState.sshKeyName` | string | read-only | Name of the SSH key pair injected into the instance at boot. Null when none was provided. |
| `currentState.userId` | string | read-only | Identifier of the OpenStack user that owns the instance |
| `currentState.volumes` | publicCloud.instance.InstanceVolume[] | read-only | Observed block volumes attached to the instance, with details (name, size). See InstanceVolume. |
| `currentState.volumes[].id` | string (uuid) | read-only | Unique identifier of the attached volume |
| `currentState.volumes[].name` | string | read-only | Display name of the attached volume |
| `currentState.volumes[].size` | integer | read-only | Size of the attached volume in GB |
| `currentTasks` | common.CurrentTask[] | read-only | In-progress operations. Ongoing asynchronous tasks reconciling currentState toward targetSpec, for example a create, resize, reboot, volume attach or share attach. Poll the instance until this list is empty and resourceStatus is READY to know the requested change has been applied. |
| `currentTasks[].errors` | common.TaskError[] | read-only | Errors that occurred on the task |
| `currentTasks[].errors[].message` | string | read-only | Error description |
| `currentTasks[].id` | string (uuid) | read-only | Identifier of the current task |
| `currentTasks[].link` | string | read-only | Link to the task details |
| `currentTasks[].status` | common.CurrentTaskStatusEnum | read-only | Current global status of the current task — one of `ERROR`, `PENDING`, `RUNNING`, `SCHEDULED`, `WAITING_USER_INPUT` |
| `currentTasks[].type` | string | read-only | Type of the current task |
| `id` | string (uuid) | read-only | Unique identifier of the instance |
| `resourceStatus` | common.ResourceStatusEnum | read-only | Resource lifecycle status. High-level readiness of the instance in the system, for example CREATING, READY, UPDATING, DELETING, ERROR. This is distinct from currentState.powerState, which carries the lower-level OpenStack administrative power state of the virtual machine. — one of `CREATING`, `CREATION_PLANNED`, `DELETING`, `ERROR`, `OUT_OF_SYNC`, `READY`, `SUSPENDED`, `UNKNOWN`, `UPDATING` |
| `targetSpec` | publicCloud.instance.InstanceReadTargetSpec | read-only | Desired specification. Last target specification requested for the instance. On update, the difference between the previous and the new targetSpec determines the operations performed (rename, resize, power change, and declarative volume/share attach-detach). |
| `targetSpec.flavor` | publicCloud.instance.InstanceFlavorRef | read-only | Reference to the flavor that sizes the instance (vCPUs, RAM, local disk). Carries only the flavor id. Changing the referenced flavor on PUT triggers a resize of the instance. |
| `targetSpec.flavor.id` | string (uuid) | yes | Identifier of the flavor to size the instance with. Changing it on update triggers a resize. |
| `targetSpec.group` | publicCloud.instance.InstanceGroupRef | read-only | Optional reference to the instance (placement) group the instance is created into, controlling affinity/anti-affinity placement. Immutable: the group is set only at creation time. OpenStack/Nova server groups are immutable. There is no group change on PUT and membership cannot be changed after the instance exists. |
| `targetSpec.group.id` | string (uuid) | yes | Identifier of the instance group. Honored only at creation time. The group cannot be changed afterward. |
| `targetSpec.image` | publicCloud.instance.InstanceImageRef | read-only | Reference to the image the instance boots from. Carries only the image id. Changing the referenced image on PUT triggers a rebuild of the instance from the new image. Null for boot-from-volume instances, which have no backing image. |
| `targetSpec.image.id` | string (uuid) | yes | Identifier of the image to boot from. Changing it on update triggers a rebuild of the instance. |
| `targetSpec.location` | publicCloud.instance.InstanceLocation | read-only | Target location. Region (and optional availability zone) where the instance is provisioned. Immutable after creation. An instance cannot be moved to another region/zone, which is why location is absent from InstanceUpdateTargetSpec. |
| `targetSpec.location.availabilityZone` | string |  | Availability zone within the region where the instance is placed. When omitted at creation the backend selects a zone automatically. Immutable after creation. |
| `targetSpec.location.region` | string | yes | Code of the region where the instance is provisioned, for example GRA11, BHS5. Immutable after creation. An instance cannot be moved to another region. |
| `targetSpec.name` | string | read-only | Desired display name of the instance. Changing it on PUT triggers a rename. |
| `targetSpec.networks` | publicCloud.instance.InstanceNetworkRef[] | read-only | Declarative list of network interfaces the instance is attached to. An entry with a subnetId, and an optional id, is a private interface, optionally carrying an ip to pin its fixed address or to associate an existing floating IP. An entry with autoAssignPublicIp alone requests a public (Ext-Net) interface with a platform-assigned public IP. An entry with ip alone attaches a public IP the project already owns, either an additional IP or an Ext-Net IP of the project in the instance's region. See InstanceNetworkRef. The list drives the desired network topology: adding or removing an entry attaches or detaches the corresponding interface on update. |
| `targetSpec.networks[].autoAssignPublicIp` | boolean |  | Auto-assign public IP. Whether to attach a public (Ext-Net) interface with a public IP assigned by the platform. Only allowed on an entry that has no id, no subnetId and no ip, and at most one entry of the networks list may set it. Requires the optional instance/usePublicIP IAM action. |
| `targetSpec.networks[].id` | string (uuid) |  | Identifier of the private network to attach to. Optional on a private interface: when omitted, the network of subnetId is used. Omit it on an entry declaring public connectivity through autoAssignPublicIp or ip. |
| `targetSpec.networks[].ip` | ip |  | Address of this interface, whose meaning depends on the sibling fields. Without an id and a subnetId: a public IP the project already owns. An additional IP, or an Ext-Net IP of the project in the instance's region. Any other address is rejected, and the entry implicitly attaches the public (Ext-Net) interface. On a private entry (subnetId, with an optional id): pins the interface's fixed address when the address falls inside the subnet CIDR, and otherwise designates an EXISTING floating IP to associate with that interface. A public address requires the optional instance/usePublicIP IAM action. |
| `targetSpec.networks[].subnetId` | string (uuid) |  | Identifier of the subnet the interface draws its fixed address from. Required for a private interface. Leave unset on an entry declaring public connectivity. |
| `targetSpec.powerState` | publicCloud.instance.PowerStateEnum | read-only | Desired administrative power state of the instance (see PowerStateEnum: ACTIVE, PAUSED, RESCUE, SHELVED, SHUTOFF, SUSPENDED). Changing it on PUT drives the corresponding power transition (start, stop, shelve, rescue, pause, suspend). Defaults to ACTIVE. — one of `ACTIVE`, `PAUSED`, `RESCUE`, `SHELVED`, `SHUTOFF`, `SUSPENDED` |
| `targetSpec.securityGroups` | publicCloud.securityGroup.SecurityGroupRef[] | read-only | Optional list of references to the security groups applied to all of the instance's ports. Each entry carries the security group id. Changing this list on PUT re-applies the resulting set of security groups to every instance port. |
| `targetSpec.securityGroups[].id` | string (uuid) | yes | Identifier of the security group |
| `targetSpec.shares` | publicCloud.instance.InstanceShareRef[] | read-only | Declarative list of file storage (shares) attached to the instance, managed exactly like volumes: the diff of this list on PUT drives attach/detach. Attaching a share creates a Manila IP access rule for the instance's interface on the share's network. The instance must have an interface on that network or the operation errors. Detaching (removing an entry from this list) deletes the matching access rule and is idempotent. Each entry's accessLevel defaults to READ_WRITE when omitted (see InstanceShareRef). |
| `targetSpec.shares[].accessLevel` | publicCloud.storage.file.FileStorageAccessLevelEnum |  | Desired access level granted to the instance for this share (see FileStorageAccessLevelEnum: READ_ONLY, READ_WRITE). Defaults to READ_WRITE. — one of `READ_ONLY`, `READ_WRITE` |
| `targetSpec.shares[].id` | string (uuid) | yes | Identifier of the file storage (share) to attach. Adding this reference attaches the share to the instance. Removing it from the shares list detaches it. |
| `targetSpec.sshKeyName` | string | read-only | Name of the SSH key pair injected into the instance at boot for initial access. Immutable / create-only: the key is injected once during provisioning and cannot be changed afterward, which is why sshKeyName is absent from InstanceUpdateTargetSpec. |
| `targetSpec.volumes` | publicCloud.instance.InstanceVolumeRef[] | read-only | Declarative list of block volumes attached to the instance, each referencing a volume by id (see InstanceVolumeRef). Attach/detach is driven by diffing this list on PUT. There is no imperative attach/detach sub-route. Adding a volume reference attaches that volume. Removing one detaches it. |
| `targetSpec.volumes[].id` | string (uuid) | yes | Identifier of the volume to attach. Adding this reference attaches the volume. Removing it from the volumes list detaches it. |
| `updatedAt` | string (date-time) | read-only | Last modification date of the instance, as an ISO 8601 / RFC 3339 timestamp |

```json
{
  "checksum": "string",
  "createdAt": "2024-01-01T12:00:00Z",
  "currentState": {
    "availableActions": [
      {
        "available": true,
        "name": "LOCK"
      }
    ],
    "flavor": {
      "bandwidth": {
        "private": 0,
        "publicInbound": 0,
        "publicOutbound": 0
      },
      "disk": 0,
      "gpus": 0,
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "string",
      "ram": 0,
      "vcpus": 0
    },
    "group": {
      "id": "00000000-0000-0000-0000-000000000000"
    },
    "hostId": "string",
    "image": {
      "defaultUser": "string",
      "deprecated": true,
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "string",
      "size": 0,
      "status": "ACTIVE"
    },
    "location": {
      "availabilityZone": "string",
      "region": "string"
    },
    "locked": true,
    "name": "string",
    "networks": [
      {
        "addresses": [
          {
            "ip": "192.0.2.0",
            "mac": "00:00:5e:00:53:01",
            "type": "ADDITIONAL",
            "version": 0
          }
        ],
        "gatewayId": "00000000-0000-0000-0000-000000000000",
        "id": "00000000-0000-0000-0000-000000000000",
        "subnetId": "00000000-0000-0000-0000-000000000000"
      }
    ],
    "powerState": "ACTIVE",
    "projectId": "string",
    "securityGroups": [
      {
        "id": "00000000-0000-0000-0000-000000000000"
      }
    ],
    "shares": [
      {
        "accessLevel": "READ_ONLY",
        "accessTo": "string",
        "id": "00000000-0000-0000-0000-000000000000",
  …
```

### Example

```bash
curl -X POST \
  "https://api.eu.ovhcloud.com/v2/publicCloud/project/{projectId}/compute/instance/{instanceId}/action" \
  -H "accept: application/json" \
  -H "authorization: Bearer $OVH_TOKEN" \
  -H "content-type: application/json" \
  -d '{ }'
```

```python
'''
First, install the latest release of Python wrapper: $ pip install ovh
'''
import json
import ovh

# Instantiate an OVH Client.
# You can generate new credentials with full access to your account on
# the token creation page (https://api.ovh.com/createToken/index.cgi?GET=/*&PUT=/*&POST=/*&DELETE=/*)
client = ovh.Client(
	endpoint='ovh-eu',               # Endpoint of API OVH (List of available endpoints: https://github.com/ovh/python-ovh#2-configure-your-application)
	application_key='xxxxxxxxxx',    # Application Key
	application_secret='xxxxxxxxxx', # Application Secret
	consumer_key='xxxxxxxxxx',       # Consumer Key
)

# Request body type: publicCloud.instance.InstanceActionRequest
result = client.post("/v2/publicCloud/project/{projectId}/compute/instance/{instanceId}/action",
	checksum = None, # Concurrency-control checksum. Optional checksum obtained from the last GET of the instance. When supplied, it must still match the instance's current checksum or the action is rejected with a 409 checksum-mismatch conflict, protecting against a concurrent modification. When omitted or empty, the concurrency check is skipped and the action is forced (last-write-wins). (type: string, nullable)
	parameters = None, # Optional parameters refining the requested action (see InstanceActionParameters). Only relevant for actions that accept options, such as a hard REBOOT or a RESCUE with a specific image. Omit for actions that take none. (type: publicCloud.instance.InstanceActionParameters, nullable)
	type = None, # Action type. The imperative action to perform on the instance (see InstanceActionTypeEnum: LOCK, UNLOCK, REBOOT, RESCUE, UNRESCUE, STOP, START, SHELVE, UNSHELVE, PAUSE, UNPAUSE, SUSPEND, RESUME). (type: publicCloud.instance.InstanceActionTypeEnum)
)

# Pretty print
print(json.dumps(result, indent=4))
```

```php
<?php
/**
 * First, download the latest release of PHP wrapper on github
 * And include this script into the folder with extracted files
 */
require __DIR__ . '/vendor/autoload.php';
use \Ovh\Api;

/**
 * Instantiate an OVH Client.
 * You can generate new credentials with full access to your account on
 * the token creation page (https://api.ovh.com/createToken/index.cgi?GET=/*&PUT=/*&POST=/*&DELETE=/*)
 */
$ovh = new Api('xxxxxxxxxx',  // Application Key
               'xxxxxxxxxx',  // Application Secret
               'ovh-eu',      // Endpoint of API OVH (List of available endpoints: https://github.com/ovh/python-ovh#2-configure-your-application)
               'xxxxxxxxxx'); // Consumer Key

// Request body type: publicCloud.instance.InstanceActionRequest
$result = $ovh->post("/v2/publicCloud/project/{projectId}/compute/instance/{instanceId}/action", array(
	checksum => null, // Concurrency-control checksum. Optional checksum obtained from the last GET of the instance. When supplied, it must still match the instance's current checksum or the action is rejected with a 409 checksum-mismatch conflict, protecting against a concurrent modification. When omitted or empty, the concurrency check is skipped and the action is forced (last-write-wins). (type: string, nullable)
	parameters => null, // Optional parameters refining the requested action (see InstanceActionParameters). Only relevant for actions that accept options, such as a hard REBOOT or a RESCUE with a specific image. Omit for actions that take none. (type: publicCloud.instance.InstanceActionParameters, nullable)
	type => null, // Action type. The imperative action to perform on the instance (see InstanceActionTypeEnum: LOCK, UNLOCK, REBOOT, RESCUE, UNRESCUE, STOP, START, SHELVE, UNSHELVE, PAUSE, UNPAUSE, SUSPEND, RESUME). (type: publicCloud.instance.InstanceActionTypeEnum)
));

print_r($result);
?>
```

## Delete an instance

`DELETE /v2/publicCloud/project/{projectId}/compute/instance/{instanceId}`

Link: https://developers.eu.ovhcloud.com/reference/public-cloud/compute/instances/#deleteInstance

**Status:** Stable production version  
**IAM actions:** `publicCloudProject:apiovh:instance/delete`

### Delete an instance

Permanently deletes a Public Cloud instance. Deletion is asynchronous: the resource transitions to `DELETING`, the response echoes the instance, and the backend then removes it. Poll `GET .../instance/{instanceId}` until it returns `InstanceDoesNotExist` (`404`) to confirm removal.

Behavior
* Independent block volumes attached to the instance are detached, not deleted — they are separate resources and survive.
* Filesystem (share) attachments are released as part of the teardown.

A delete already in progress is reported as `ResourceAlreadyBeingDeleted`. An instance in a transient or otherwise invalid state may be rejected with `ResourceInInvalidState`.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `instanceId` | path | string (uuid) | yes | Instance ID |
| `projectId` | path | string | yes | Project ID |

### Responses

| Status | Type | Description |
| --- | --- | --- |
| 200 | publicCloud.instance.Instance | successful operation |
| 404 | object | Error 404 response |
| 409 | object | Error 409 response |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `checksum` | string | read-only | Computed hash representing the current targetSpec value. It enables optional optimistic concurrency control: the value returned by a GET may be sent back in the PUT and action payloads, and the request is then rejected with a 409 checksum-mismatch conflict if it no longer matches server-side (because another request modified the instance in the meantime). Sending no checksum skips that check and forces the write (last-write-wins). |
| `createdAt` | string (date-time) | read-only | Creation date of the instance, as an ISO 8601 / RFC 3339 timestamp |
| `currentState` | publicCloud.instance.InstanceCurrentState | read-only | Current observed state of the instance as reported by the compute backend (name, flavor, image, location, power state, networks, attached volumes, attached shares, security groups). It is null while the instance is still being created and no backend state is available yet. |
| `currentState.availableActions` | publicCloud.instance.InstanceAvailableAction[] | read-only | Availability of every instance action type given the current state of the instance. Always contains exactly one entry per InstanceActionTypeEnum value, in the order of that enum, each flagged with whether it can currently be triggered through the action endpoint. For example, when the instance is locked only UNLOCK is available. While a task is in progress on the instance or when it is in error, none is available. |
| `currentState.availableActions[].available` | boolean | read-only | Whether the action can currently be triggered through the action endpoint. A call with an unavailable action is refused. |
| `currentState.availableActions[].name` | publicCloud.instance.InstanceActionTypeEnum | read-only | Action type, as accepted by the action endpoint — one of `LOCK`, `PAUSE`, `REBOOT`, `RESCUE`, `RESUME`, `SHELVE`, `START`, `STOP`, `SUSPEND`, `UNLOCK`, `UNPAUSE`, `UNRESCUE`, … |
| `currentState.flavor` | publicCloud.instance.InstanceFlavor | read-only | Observed flavor of the instance with full details (name, vCPUs, RAM, local disk). See InstanceFlavor. |
| `currentState.flavor.bandwidth` | publicCloud.instance.FlavorBandwidth | read-only | Network bandwidth of the flavor in Mbit/s. Null when the flavor is not in the catalog. |
| `currentState.flavor.disk` | integer | read-only | Size of the flavor's local root disk in GB |
| `currentState.flavor.gpus` | integer | read-only | Number of physical GPUs provided by the flavor, 0 for flavors without GPU |
| `currentState.flavor.id` | string (uuid) | read-only | Unique identifier of the flavor |
| `currentState.flavor.name` | string | read-only | Human-readable flavor name, for example the commercial flavor label |
| `currentState.flavor.ram` | integer | read-only | Amount of RAM provided by the flavor in MB |
| `currentState.flavor.vcpus` | integer | read-only | Number of virtual CPUs provided by the flavor |
| `currentState.group` | publicCloud.instance.InstanceGroupRef | read-only | Reference to the instance (placement) group the instance belongs to. Null when it is not part of any group. Immutable after creation. |
| `currentState.group.id` | string (uuid) | yes | Identifier of the instance group. Honored only at creation time. The group cannot be changed afterward. |
| `currentState.hostId` | string | read-only | Opaque identifier of the physical host the instance is running on, as exposed by OpenStack. Null when not available. |
| `currentState.image` | publicCloud.instance.InstanceImage | read-only | Observed image the instance was booted from, with full details (name, size, status). Null for boot-from-volume instances, which have no image. See InstanceImage. |
| `currentState.image.defaultUser` | string | read-only | Default login user of the image, as set by its publisher, for example almalinux or ubuntu. Null when the image declares none. |
| `currentState.image.deprecated` | boolean | read-only | Whether the image is flagged as deprecated. A deprecated image can still boot existing instances but is no longer recommended for new ones. |
| `currentState.image.id` | string (uuid) | read-only | Unique identifier of the image |
| `currentState.image.name` | string | read-only | Human-readable image name. Null when not reported by the backend. |
| `currentState.image.size` | integer | read-only | Size of the image in bytes. Null when the backend does not report it. |
| `currentState.image.status` | publicCloud.instance.ImageStatusEnum | read-only | Lifecycle status of the image as reported by Glance (see ImageStatusEnum). Null when not reported. — one of `ACTIVE`, `DEACTIVATED`, `DELETED`, `IMPORTING`, `KILLED`, `PENDING_DELETE`, `QUEUED`, `SAVING` |
| `currentState.location` | publicCloud.instance.InstanceLocation | read-only | Location. Observed region and availability zone where the instance is provisioned. See InstanceLocation. |
| `currentState.location.availabilityZone` | string |  | Availability zone within the region where the instance is placed. When omitted at creation the backend selects a zone automatically. Immutable after creation. |
| `currentState.location.region` | string | yes | Code of the region where the instance is provisioned, for example GRA11, BHS5. Immutable after creation. An instance cannot be moved to another region. |
| `currentState.locked` | boolean | read-only | Lock state. Whether the instance is locked against modifications. When locked, mutating actions are refused until it is unlocked (see the LOCK/UNLOCK actions in InstanceActionTypeEnum). |
| `currentState.name` | string | read-only | Observed display name of the instance |
| `currentState.networks` | publicCloud.instance.InstanceNetwork[] | read-only | Observed network interfaces of the instance, with full details (network, subnet, gateway and per-interface addresses). One entry per network, plus at most one entry without an id for the public (Ext-Net) interface. Every address of the instance is reported through the entry's addresses list, each address typed FIXED, FLOATING or ADDITIONAL. There is no separate scalar address field. See InstanceNetwork. |
| `currentState.networks[].addresses` | publicCloud.instance.InstanceNetworkAddress[] | read-only | Every IP address through which the instance is reachable on this interface, each with its type, IP version and MAC address. It carries the interface's fixed addresses and, where applicable, the floating IP associated with it and any additional IPs routed to it. This is the single source of truth for the instance's observed addresses. Null or empty only while no address has been assigned yet. See InstanceNetworkAddress. |
| `currentState.networks[].gatewayId` | string (uuid) | read-only | Identifier of the gateway providing egress for this interface. Null when none applies. |
| `currentState.networks[].id` | string (uuid) | read-only | Identifier of the network this interface is attached to, or null for the public (Ext-Net) interface. There is at most one entry without an id: additional IPs are reported as ADDITIONAL addresses of that public entry instead of forming their own entry. |
| `currentState.networks[].subnetId` | string (uuid) | read-only | Identifier of the subnet this interface draws its fixed address from, or null for an entry without a network id |
| `currentState.powerState` | publicCloud.instance.PowerStateEnum | read-only | Actual administrative power state of the instance as reported by OpenStack (see PowerStateEnum). This may transiently differ from targetSpec.powerState while a power transition is in progress. — one of `ACTIVE`, `PAUSED`, `RESCUE`, `SHELVED`, `SHUTOFF`, `SUSPENDED` |
| `currentState.projectId` | string | read-only | Identifier of the Public Cloud project the instance belongs to |
| `currentState.securityGroups` | publicCloud.securityGroup.SecurityGroupRef[] | read-only | References to the security groups currently attached to the instance's ports |
| `currentState.securityGroups[].id` | string (uuid) | yes | Identifier of the security group |
| `currentState.shares` | publicCloud.instance.InstanceShare[] | read-only | Observed instance-side share attachments. Only populated on a GET of a single instance (never in list responses). Mixing per-share access rules (managed directly on the share resource) with instance-side attach on the same share is unsupported and will show the share OUT_OF_SYNC. See InstanceShare. |
| `currentState.shares[].accessLevel` | publicCloud.storage.file.FileStorageAccessLevelEnum | read-only | Observed access level of the access rule for this instance (see FileStorageAccessLevelEnum: READ_ONLY, READ_WRITE) — one of `READ_ONLY`, `READ_WRITE` |
| `currentState.shares[].accessTo` | string | read-only | The instance IP address the Manila access rule targets. The instance's fixed IPv4 address on the share's network. |
| `currentState.shares[].id` | string (uuid) | read-only | Identifier of the attached file storage (share) |
| `currentState.shares[].state` | publicCloud.storage.file.FileStorageAccessRuleStateEnum | read-only | Observed state of the underlying access rule (see FileStorageAccessRuleStateEnum: ACTIVE, APPLYING, DENYING, ERROR). Null while no state has been reported yet. — one of `ACTIVE`, `APPLYING`, `DENYING`, `ERROR` |
| `currentState.sshKeyName` | string | read-only | Name of the SSH key pair injected into the instance at boot. Null when none was provided. |
| `currentState.userId` | string | read-only | Identifier of the OpenStack user that owns the instance |
| `currentState.volumes` | publicCloud.instance.InstanceVolume[] | read-only | Observed block volumes attached to the instance, with details (name, size). See InstanceVolume. |
| `currentState.volumes[].id` | string (uuid) | read-only | Unique identifier of the attached volume |
| `currentState.volumes[].name` | string | read-only | Display name of the attached volume |
| `currentState.volumes[].size` | integer | read-only | Size of the attached volume in GB |
| `currentTasks` | common.CurrentTask[] | read-only | In-progress operations. Ongoing asynchronous tasks reconciling currentState toward targetSpec, for example a create, resize, reboot, volume attach or share attach. Poll the instance until this list is empty and resourceStatus is READY to know the requested change has been applied. |
| `currentTasks[].errors` | common.TaskError[] | read-only | Errors that occurred on the task |
| `currentTasks[].errors[].message` | string | read-only | Error description |
| `currentTasks[].id` | string (uuid) | read-only | Identifier of the current task |
| `currentTasks[].link` | string | read-only | Link to the task details |
| `currentTasks[].status` | common.CurrentTaskStatusEnum | read-only | Current global status of the current task — one of `ERROR`, `PENDING`, `RUNNING`, `SCHEDULED`, `WAITING_USER_INPUT` |
| `currentTasks[].type` | string | read-only | Type of the current task |
| `id` | string (uuid) | read-only | Unique identifier of the instance |
| `resourceStatus` | common.ResourceStatusEnum | read-only | Resource lifecycle status. High-level readiness of the instance in the system, for example CREATING, READY, UPDATING, DELETING, ERROR. This is distinct from currentState.powerState, which carries the lower-level OpenStack administrative power state of the virtual machine. — one of `CREATING`, `CREATION_PLANNED`, `DELETING`, `ERROR`, `OUT_OF_SYNC`, `READY`, `SUSPENDED`, `UNKNOWN`, `UPDATING` |
| `targetSpec` | publicCloud.instance.InstanceReadTargetSpec | read-only | Desired specification. Last target specification requested for the instance. On update, the difference between the previous and the new targetSpec determines the operations performed (rename, resize, power change, and declarative volume/share attach-detach). |
| `targetSpec.flavor` | publicCloud.instance.InstanceFlavorRef | read-only | Reference to the flavor that sizes the instance (vCPUs, RAM, local disk). Carries only the flavor id. Changing the referenced flavor on PUT triggers a resize of the instance. |
| `targetSpec.flavor.id` | string (uuid) | yes | Identifier of the flavor to size the instance with. Changing it on update triggers a resize. |
| `targetSpec.group` | publicCloud.instance.InstanceGroupRef | read-only | Optional reference to the instance (placement) group the instance is created into, controlling affinity/anti-affinity placement. Immutable: the group is set only at creation time. OpenStack/Nova server groups are immutable. There is no group change on PUT and membership cannot be changed after the instance exists. |
| `targetSpec.group.id` | string (uuid) | yes | Identifier of the instance group. Honored only at creation time. The group cannot be changed afterward. |
| `targetSpec.image` | publicCloud.instance.InstanceImageRef | read-only | Reference to the image the instance boots from. Carries only the image id. Changing the referenced image on PUT triggers a rebuild of the instance from the new image. Null for boot-from-volume instances, which have no backing image. |
| `targetSpec.image.id` | string (uuid) | yes | Identifier of the image to boot from. Changing it on update triggers a rebuild of the instance. |
| `targetSpec.location` | publicCloud.instance.InstanceLocation | read-only | Target location. Region (and optional availability zone) where the instance is provisioned. Immutable after creation. An instance cannot be moved to another region/zone, which is why location is absent from InstanceUpdateTargetSpec. |
| `targetSpec.location.availabilityZone` | string |  | Availability zone within the region where the instance is placed. When omitted at creation the backend selects a zone automatically. Immutable after creation. |
| `targetSpec.location.region` | string | yes | Code of the region where the instance is provisioned, for example GRA11, BHS5. Immutable after creation. An instance cannot be moved to another region. |
| `targetSpec.name` | string | read-only | Desired display name of the instance. Changing it on PUT triggers a rename. |
| `targetSpec.networks` | publicCloud.instance.InstanceNetworkRef[] | read-only | Declarative list of network interfaces the instance is attached to. An entry with a subnetId, and an optional id, is a private interface, optionally carrying an ip to pin its fixed address or to associate an existing floating IP. An entry with autoAssignPublicIp alone requests a public (Ext-Net) interface with a platform-assigned public IP. An entry with ip alone attaches a public IP the project already owns, either an additional IP or an Ext-Net IP of the project in the instance's region. See InstanceNetworkRef. The list drives the desired network topology: adding or removing an entry attaches or detaches the corresponding interface on update. |
| `targetSpec.networks[].autoAssignPublicIp` | boolean |  | Auto-assign public IP. Whether to attach a public (Ext-Net) interface with a public IP assigned by the platform. Only allowed on an entry that has no id, no subnetId and no ip, and at most one entry of the networks list may set it. Requires the optional instance/usePublicIP IAM action. |
| `targetSpec.networks[].id` | string (uuid) |  | Identifier of the private network to attach to. Optional on a private interface: when omitted, the network of subnetId is used. Omit it on an entry declaring public connectivity through autoAssignPublicIp or ip. |
| `targetSpec.networks[].ip` | ip |  | Address of this interface, whose meaning depends on the sibling fields. Without an id and a subnetId: a public IP the project already owns. An additional IP, or an Ext-Net IP of the project in the instance's region. Any other address is rejected, and the entry implicitly attaches the public (Ext-Net) interface. On a private entry (subnetId, with an optional id): pins the interface's fixed address when the address falls inside the subnet CIDR, and otherwise designates an EXISTING floating IP to associate with that interface. A public address requires the optional instance/usePublicIP IAM action. |
| `targetSpec.networks[].subnetId` | string (uuid) |  | Identifier of the subnet the interface draws its fixed address from. Required for a private interface. Leave unset on an entry declaring public connectivity. |
| `targetSpec.powerState` | publicCloud.instance.PowerStateEnum | read-only | Desired administrative power state of the instance (see PowerStateEnum: ACTIVE, PAUSED, RESCUE, SHELVED, SHUTOFF, SUSPENDED). Changing it on PUT drives the corresponding power transition (start, stop, shelve, rescue, pause, suspend). Defaults to ACTIVE. — one of `ACTIVE`, `PAUSED`, `RESCUE`, `SHELVED`, `SHUTOFF`, `SUSPENDED` |
| `targetSpec.securityGroups` | publicCloud.securityGroup.SecurityGroupRef[] | read-only | Optional list of references to the security groups applied to all of the instance's ports. Each entry carries the security group id. Changing this list on PUT re-applies the resulting set of security groups to every instance port. |
| `targetSpec.securityGroups[].id` | string (uuid) | yes | Identifier of the security group |
| `targetSpec.shares` | publicCloud.instance.InstanceShareRef[] | read-only | Declarative list of file storage (shares) attached to the instance, managed exactly like volumes: the diff of this list on PUT drives attach/detach. Attaching a share creates a Manila IP access rule for the instance's interface on the share's network. The instance must have an interface on that network or the operation errors. Detaching (removing an entry from this list) deletes the matching access rule and is idempotent. Each entry's accessLevel defaults to READ_WRITE when omitted (see InstanceShareRef). |
| `targetSpec.shares[].accessLevel` | publicCloud.storage.file.FileStorageAccessLevelEnum |  | Desired access level granted to the instance for this share (see FileStorageAccessLevelEnum: READ_ONLY, READ_WRITE). Defaults to READ_WRITE. — one of `READ_ONLY`, `READ_WRITE` |
| `targetSpec.shares[].id` | string (uuid) | yes | Identifier of the file storage (share) to attach. Adding this reference attaches the share to the instance. Removing it from the shares list detaches it. |
| `targetSpec.sshKeyName` | string | read-only | Name of the SSH key pair injected into the instance at boot for initial access. Immutable / create-only: the key is injected once during provisioning and cannot be changed afterward, which is why sshKeyName is absent from InstanceUpdateTargetSpec. |
| `targetSpec.volumes` | publicCloud.instance.InstanceVolumeRef[] | read-only | Declarative list of block volumes attached to the instance, each referencing a volume by id (see InstanceVolumeRef). Attach/detach is driven by diffing this list on PUT. There is no imperative attach/detach sub-route. Adding a volume reference attaches that volume. Removing one detaches it. |
| `targetSpec.volumes[].id` | string (uuid) | yes | Identifier of the volume to attach. Adding this reference attaches the volume. Removing it from the volumes list detaches it. |
| `updatedAt` | string (date-time) | read-only | Last modification date of the instance, as an ISO 8601 / RFC 3339 timestamp |

```json
{
  "checksum": "string",
  "createdAt": "2024-01-01T12:00:00Z",
  "currentState": {
    "availableActions": [
      {
        "available": true,
        "name": "LOCK"
      }
    ],
    "flavor": {
      "bandwidth": {
        "private": 0,
        "publicInbound": 0,
        "publicOutbound": 0
      },
      "disk": 0,
      "gpus": 0,
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "string",
      "ram": 0,
      "vcpus": 0
    },
    "group": {
      "id": "00000000-0000-0000-0000-000000000000"
    },
    "hostId": "string",
    "image": {
      "defaultUser": "string",
      "deprecated": true,
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "string",
      "size": 0,
      "status": "ACTIVE"
    },
    "location": {
      "availabilityZone": "string",
      "region": "string"
    },
    "locked": true,
    "name": "string",
    "networks": [
      {
        "addresses": [
          {
            "ip": "192.0.2.0",
            "mac": "00:00:5e:00:53:01",
            "type": "ADDITIONAL",
            "version": 0
          }
        ],
        "gatewayId": "00000000-0000-0000-0000-000000000000",
        "id": "00000000-0000-0000-0000-000000000000",
        "subnetId": "00000000-0000-0000-0000-000000000000"
      }
    ],
    "powerState": "ACTIVE",
    "projectId": "string",
    "securityGroups": [
      {
        "id": "00000000-0000-0000-0000-000000000000"
      }
    ],
    "shares": [
      {
        "accessLevel": "READ_ONLY",
        "accessTo": "string",
        "id": "00000000-0000-0000-0000-000000000000",
  …
```

### Example

```bash
curl -X DELETE \
  "https://api.eu.ovhcloud.com/v2/publicCloud/project/{projectId}/compute/instance/{instanceId}" \
  -H "accept: application/json" \
  -H "authorization: Bearer $OVH_TOKEN"
```

```python
'''
First, install the latest release of Python wrapper: $ pip install ovh
'''
import json
import ovh

# Instantiate an OVH Client.
# You can generate new credentials with full access to your account on
# the token creation page (https://api.ovh.com/createToken/index.cgi?GET=/*&PUT=/*&POST=/*&DELETE=/*)
client = ovh.Client(
	endpoint='ovh-eu',               # Endpoint of API OVH (List of available endpoints: https://github.com/ovh/python-ovh#2-configure-your-application)
	application_key='xxxxxxxxxx',    # Application Key
	application_secret='xxxxxxxxxx', # Application Secret
	consumer_key='xxxxxxxxxx',       # Consumer Key
)

result = client.delete("/v2/publicCloud/project/{projectId}/compute/instance/{instanceId}")

# Pretty print
print(json.dumps(result, indent=4))
```

```php
<?php
/**
 * First, download the latest release of PHP wrapper on github
 * And include this script into the folder with extracted files
 */
require __DIR__ . '/vendor/autoload.php';
use \Ovh\Api;

/**
 * Instantiate an OVH Client.
 * You can generate new credentials with full access to your account on
 * the token creation page (https://api.ovh.com/createToken/index.cgi?GET=/*&PUT=/*&POST=/*&DELETE=/*)
 */
$ovh = new Api('xxxxxxxxxx',  // Application Key
               'xxxxxxxxxx',  // Application Secret
               'ovh-eu',      // Endpoint of API OVH (List of available endpoints: https://github.com/ovh/python-ovh#2-configure-your-application)
               'xxxxxxxxxx'); // Consumer Key

$result = $ovh->delete("/v2/publicCloud/project/{projectId}/compute/instance/{instanceId}");

print_r($result);
?>
```

## Update an instance

`PUT /v2/publicCloud/project/{projectId}/compute/instance/{instanceId}`

Link: https://developers.eu.ovhcloud.com/reference/public-cloud/compute/instances/#editInstance

**Status:** Stable production version  
**IAM actions:** `publicCloudProject:apiovh:instance/edit`, `publicCloudProject:apiovh:instance/usePublicIP`

### Update an instance

This is the single, declarative route for changing an instance. You do not call verb-specific endpoints. Instead you submit a new desired `targetSpec` and the API derives the operations to perform from the diff against the current specification. (Imperative power/lifecycle operations such as reboot, start, stop, and rescue live on the separate `.../instance/{instanceId}/action` route.)

### Asynchronous, desired-state model
1. You send the new `targetSpec`, optionally together with the `checksum` from your last `GET`.
2. If accepted, you immediately get back the instance with the updated `targetSpec` and a new `checksum`. `resourceStatus` becomes `UPDATING`.
3. One or more asynchronous tasks reconcile `currentState` toward `targetSpec`. Poll `GET .../instance/{instanceId}` until `resourceStatus` is `READY` and `currentTasks` is empty to know the change has been applied.

### Operations derived from the diff
* Rename — changing `name` renames the instance.
* Resize (flavor) — changing `flavor` migrates the instance to the new flavor.
* Volume attach / detach — done declaratively by diffing the `volumes` list: adding a volume reference attaches that volume, removing one detaches it. There is no imperative attach/detach endpoint — the diff is the only mechanism.
* Network attach / detach — done declaratively by diffing the `networks` list, whose entries are `{id?, subnetId?, ip?, autoAssignPublicIp?}`: a platform-assigned Ext-Net IP (`{"autoAssignPublicIp": true}`, at most one entry), a public IP the project already owns — additional IP or project Ext-Net IP in the instance's region — (`{"ip"}`, no network `id`), a private interface with an IPAM address (`{"id", "subnetId"}`), or a private interface with `ip` either pinning its fixed address (address inside the subnet CIDR) or associating an existing floating IP (address outside it). Any entry that sets `autoAssignPublicIp` or carries a public `ip` requires the optional `instance/usePublicIP` IAM action.
* Filesystem (share) attach / detach — done declaratively by diffing the `shares` list. Adding an entry attaches the share: it creates a Manila IP access rule for the instance's interface on the share's network, so the instance must already have an interface on that network or the attach errors. Removing an entry detaches the share: the matching access rule is removed, and the detach is idempotent. Each entry's `accessLevel` defaults to `READ_WRITE`. Caveat: managing per-share access rules directly on the share resource *and* attaching the same share instance-side here is unsupported — the share will report `OUT_OF_SYNC`.

### Immutable fields (excluded from update)
`location`, `sshKeyName`, and `group` are set only at creation and are not part of the update. In particular, placement-group (`group`) membership cannot change post-create. OpenStack/Nova server groups are immutable and there is deliberately no group `PUT`.

### Destructive update (`userData`)
Changing `targetSpec.userData` reinstalls the instance — a Nova rebuild on its current image — which wipes the root disk and all data on it. Semantics are tri-state: omitting the field (or sending `null`) keeps the current value unchanged, an empty string `""` clears it, and any other value replaces it. Both the clear and the replace trigger the reinstall. An instance with no `image` (boot-from-volume) has nothing to rebuild onto, so a `userData` change on it is rejected with a `400 InvalidParameter`.

### Optimistic concurrency (`checksum`)
The `checksum` guards against lost updates and is optional. When you send it, it must match the server-side value: if another request modified the instance since your last `GET`, the checksum no longer matches and the request is rejected with a checksum-mismatch error (`ChecksumMismatch`). Re-`GET` the instance and retry against the fresh state. When you omit it (or send an empty string), the check is skipped and the update is forced (last-write-wins).

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `instanceId` | path | string (uuid) | yes | Instance ID |
| `projectId` | path | string | yes | Project ID |

### Request body (required)

Type: `publicCloud.instance.InstanceUpdate`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `checksum` | string |  | Concurrency-control checksum. Optional checksum obtained from the last GET of the instance. When supplied, it must still match the instance's current checksum or the update is rejected with a 409 checksum-mismatch conflict, protecting against a concurrent modification. When omitted or empty, the concurrency check is skipped and the update is forced (last-write-wins). |
| `targetSpec` | publicCloud.instance.InstanceUpdateTargetSpec | yes | Desired specification (mutable fields). Updated target specification restricted to the fields that can change after creation. Immutable fields (location, sshKeyName, placement group) are intentionally absent. See InstanceUpdateTargetSpec. userData is write-only (never echoed back) and follows tri-state semantics. Changing it (clearing or replacing) reinstalls the instance. |
| `targetSpec.flavor` | publicCloud.instance.InstanceFlavorRef | yes | Reference to the desired flavor (vCPUs, RAM, local disk). Carries only the flavor id. Sending a different flavor triggers a resize of the instance. |
| `targetSpec.flavor.id` | string (uuid) | yes | Identifier of the flavor to size the instance with. Changing it on update triggers a resize. |
| `targetSpec.image` | publicCloud.instance.InstanceImageRef |  | Reference to the desired image. Carries only the image id. Sending a different image triggers a rebuild of the instance from the new image. |
| `targetSpec.image.id` | string (uuid) | yes | Identifier of the image to boot from. Changing it on update triggers a rebuild of the instance. |
| `targetSpec.name` | string | yes | Desired display name of the instance. Changing it triggers a rename. |
| `targetSpec.networks` | publicCloud.instance.InstanceNetworkRef[] |  | Declarative list of network interfaces the instance is attached to (see InstanceNetworkRef). The list drives the desired network topology: adding or removing an entry attaches or detaches the corresponding interface. |
| `targetSpec.networks[].autoAssignPublicIp` | boolean |  | Auto-assign public IP. Whether to attach a public (Ext-Net) interface with a public IP assigned by the platform. Only allowed on an entry that has no id, no subnetId and no ip, and at most one entry of the networks list may set it. Requires the optional instance/usePublicIP IAM action. |
| `targetSpec.networks[].id` | string (uuid) |  | Identifier of the private network to attach to. Optional on a private interface: when omitted, the network of subnetId is used. Omit it on an entry declaring public connectivity through autoAssignPublicIp or ip. |
| `targetSpec.networks[].ip` | ip |  | Address of this interface, whose meaning depends on the sibling fields. Without an id and a subnetId: a public IP the project already owns. An additional IP, or an Ext-Net IP of the project in the instance's region. Any other address is rejected, and the entry implicitly attaches the public (Ext-Net) interface. On a private entry (subnetId, with an optional id): pins the interface's fixed address when the address falls inside the subnet CIDR, and otherwise designates an EXISTING floating IP to associate with that interface. A public address requires the optional instance/usePublicIP IAM action. |
| `targetSpec.networks[].subnetId` | string (uuid) |  | Identifier of the subnet the interface draws its fixed address from. Required for a private interface. Leave unset on an entry declaring public connectivity. |
| `targetSpec.powerState` | publicCloud.instance.PowerStateEnum |  | Desired administrative power state (see PowerStateEnum: ACTIVE, PAUSED, RESCUE, SHELVED, SHUTOFF, SUSPENDED). Changing it drives the corresponding power transition (start, stop, shelve, rescue, pause, suspend). A move OpenStack cannot make in one step, such as PAUSED to SHUTOFF, is rejected with ResourceInInvalidState before anything changes. The error message gives the route through ACTIVE. Defaults to ACTIVE. — one of `ACTIVE`, `PAUSED`, `RESCUE`, `SHELVED`, `SHUTOFF`, `SUSPENDED` |
| `targetSpec.securityGroups` | publicCloud.securityGroup.SecurityGroupRef[] |  | Optional list of references to the security groups applied to all of the instance's ports. Changing this list re-applies the resulting set of security groups to every instance port. |
| `targetSpec.securityGroups[].id` | string (uuid) | yes | Identifier of the security group |
| `targetSpec.shares` | publicCloud.instance.InstanceShareRef[] |  | Declarative list of file storage (shares) attached to the instance, managed exactly like volumes: the diff of this list drives attach/detach. Attaching a share creates a Manila IP access rule for the instance's interface on the share's network. The instance must have an interface on that network or the operation errors. Detaching (removing an entry from this list) deletes the matching access rule and is idempotent. Each entry's accessLevel defaults to READ_WRITE when omitted (see InstanceShareRef). |
| `targetSpec.shares[].accessLevel` | publicCloud.storage.file.FileStorageAccessLevelEnum |  | Desired access level granted to the instance for this share (see FileStorageAccessLevelEnum: READ_ONLY, READ_WRITE). Defaults to READ_WRITE. — one of `READ_ONLY`, `READ_WRITE` |
| `targetSpec.shares[].id` | string (uuid) | yes | Identifier of the file storage (share) to attach. Adding this reference attaches the share to the instance. Removing it from the shares list detaches it. |
| `targetSpec.userData` | string |  | User data (cloud-init). Base64-encoded (strict standard encoding) cloud-init payload, at most 65535 bytes once base64-encoded. Write-only: never returned by GET/LIST. Not persisted or stored by the Public Cloud API: the payload is handed to the compute service, which makes it available to the instance via the metadata service on boot/rebuild. Only a non-reversible fingerprint of the value is retained, for change detection. Tri-state: omitted or null keeps the current value unchanged. An empty string clears it. A non-empty value replaces it. Destructive: any change (clear or replace) REINSTALLS the instance — a Nova rebuild on the current image — wiping the root disk and all data on it. |
| `targetSpec.volumes` | publicCloud.instance.InstanceVolumeRef[] |  | Declarative list of block volumes attached to the instance (see InstanceVolumeRef). Attach/detach is driven by diffing this list. Adding a reference attaches the volume, removing one detaches it. There is no imperative attach/detach sub-route. |
| `targetSpec.volumes[].id` | string (uuid) | yes | Identifier of the volume to attach. Adding this reference attaches the volume. Removing it from the volumes list detaches it. |

```json
{
  "checksum": "string",
  "targetSpec": {
    "flavor": {
      "id": "00000000-0000-0000-0000-000000000000"
    },
    "image": {
      "id": "00000000-0000-0000-0000-000000000000"
    },
    "name": "string",
    "networks": [
      {
        "autoAssignPublicIp": true,
        "id": "00000000-0000-0000-0000-000000000000",
        "ip": "192.0.2.0",
        "subnetId": "00000000-0000-0000-0000-000000000000"
      }
    ],
    "powerState": "ACTIVE",
    "securityGroups": [
      {
        "id": "00000000-0000-0000-0000-000000000000"
      }
    ],
    "shares": [
      {
        "accessLevel": "READ_ONLY",
        "id": "00000000-0000-0000-0000-000000000000"
      }
    ],
    "userData": "string",
    "volumes": [
      {
        "id": "00000000-0000-0000-0000-000000000000"
      }
    ]
  }
}
```

### Responses

| Status | Type | Description |
| --- | --- | --- |
| 200 | publicCloud.instance.Instance | successful operation |
| 400 | object | Error 400 response |
| 404 | object | Error 404 response |
| 409 | object | Error 409 response |

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `checksum` | string | read-only | Computed hash representing the current targetSpec value. It enables optional optimistic concurrency control: the value returned by a GET may be sent back in the PUT and action payloads, and the request is then rejected with a 409 checksum-mismatch conflict if it no longer matches server-side (because another request modified the instance in the meantime). Sending no checksum skips that check and forces the write (last-write-wins). |
| `createdAt` | string (date-time) | read-only | Creation date of the instance, as an ISO 8601 / RFC 3339 timestamp |
| `currentState` | publicCloud.instance.InstanceCurrentState | read-only | Current observed state of the instance as reported by the compute backend (name, flavor, image, location, power state, networks, attached volumes, attached shares, security groups). It is null while the instance is still being created and no backend state is available yet. |
| `currentState.availableActions` | publicCloud.instance.InstanceAvailableAction[] | read-only | Availability of every instance action type given the current state of the instance. Always contains exactly one entry per InstanceActionTypeEnum value, in the order of that enum, each flagged with whether it can currently be triggered through the action endpoint. For example, when the instance is locked only UNLOCK is available. While a task is in progress on the instance or when it is in error, none is available. |
| `currentState.availableActions[].available` | boolean | read-only | Whether the action can currently be triggered through the action endpoint. A call with an unavailable action is refused. |
| `currentState.availableActions[].name` | publicCloud.instance.InstanceActionTypeEnum | read-only | Action type, as accepted by the action endpoint — one of `LOCK`, `PAUSE`, `REBOOT`, `RESCUE`, `RESUME`, `SHELVE`, `START`, `STOP`, `SUSPEND`, `UNLOCK`, `UNPAUSE`, `UNRESCUE`, … |
| `currentState.flavor` | publicCloud.instance.InstanceFlavor | read-only | Observed flavor of the instance with full details (name, vCPUs, RAM, local disk). See InstanceFlavor. |
| `currentState.flavor.bandwidth` | publicCloud.instance.FlavorBandwidth | read-only | Network bandwidth of the flavor in Mbit/s. Null when the flavor is not in the catalog. |
| `currentState.flavor.disk` | integer | read-only | Size of the flavor's local root disk in GB |
| `currentState.flavor.gpus` | integer | read-only | Number of physical GPUs provided by the flavor, 0 for flavors without GPU |
| `currentState.flavor.id` | string (uuid) | read-only | Unique identifier of the flavor |
| `currentState.flavor.name` | string | read-only | Human-readable flavor name, for example the commercial flavor label |
| `currentState.flavor.ram` | integer | read-only | Amount of RAM provided by the flavor in MB |
| `currentState.flavor.vcpus` | integer | read-only | Number of virtual CPUs provided by the flavor |
| `currentState.group` | publicCloud.instance.InstanceGroupRef | read-only | Reference to the instance (placement) group the instance belongs to. Null when it is not part of any group. Immutable after creation. |
| `currentState.group.id` | string (uuid) | yes | Identifier of the instance group. Honored only at creation time. The group cannot be changed afterward. |
| `currentState.hostId` | string | read-only | Opaque identifier of the physical host the instance is running on, as exposed by OpenStack. Null when not available. |
| `currentState.image` | publicCloud.instance.InstanceImage | read-only | Observed image the instance was booted from, with full details (name, size, status). Null for boot-from-volume instances, which have no image. See InstanceImage. |
| `currentState.image.defaultUser` | string | read-only | Default login user of the image, as set by its publisher, for example almalinux or ubuntu. Null when the image declares none. |
| `currentState.image.deprecated` | boolean | read-only | Whether the image is flagged as deprecated. A deprecated image can still boot existing instances but is no longer recommended for new ones. |
| `currentState.image.id` | string (uuid) | read-only | Unique identifier of the image |
| `currentState.image.name` | string | read-only | Human-readable image name. Null when not reported by the backend. |
| `currentState.image.size` | integer | read-only | Size of the image in bytes. Null when the backend does not report it. |
| `currentState.image.status` | publicCloud.instance.ImageStatusEnum | read-only | Lifecycle status of the image as reported by Glance (see ImageStatusEnum). Null when not reported. — one of `ACTIVE`, `DEACTIVATED`, `DELETED`, `IMPORTING`, `KILLED`, `PENDING_DELETE`, `QUEUED`, `SAVING` |
| `currentState.location` | publicCloud.instance.InstanceLocation | read-only | Location. Observed region and availability zone where the instance is provisioned. See InstanceLocation. |
| `currentState.location.availabilityZone` | string |  | Availability zone within the region where the instance is placed. When omitted at creation the backend selects a zone automatically. Immutable after creation. |
| `currentState.location.region` | string | yes | Code of the region where the instance is provisioned, for example GRA11, BHS5. Immutable after creation. An instance cannot be moved to another region. |
| `currentState.locked` | boolean | read-only | Lock state. Whether the instance is locked against modifications. When locked, mutating actions are refused until it is unlocked (see the LOCK/UNLOCK actions in InstanceActionTypeEnum). |
| `currentState.name` | string | read-only | Observed display name of the instance |
| `currentState.networks` | publicCloud.instance.InstanceNetwork[] | read-only | Observed network interfaces of the instance, with full details (network, subnet, gateway and per-interface addresses). One entry per network, plus at most one entry without an id for the public (Ext-Net) interface. Every address of the instance is reported through the entry's addresses list, each address typed FIXED, FLOATING or ADDITIONAL. There is no separate scalar address field. See InstanceNetwork. |
| `currentState.networks[].addresses` | publicCloud.instance.InstanceNetworkAddress[] | read-only | Every IP address through which the instance is reachable on this interface, each with its type, IP version and MAC address. It carries the interface's fixed addresses and, where applicable, the floating IP associated with it and any additional IPs routed to it. This is the single source of truth for the instance's observed addresses. Null or empty only while no address has been assigned yet. See InstanceNetworkAddress. |
| `currentState.networks[].gatewayId` | string (uuid) | read-only | Identifier of the gateway providing egress for this interface. Null when none applies. |
| `currentState.networks[].id` | string (uuid) | read-only | Identifier of the network this interface is attached to, or null for the public (Ext-Net) interface. There is at most one entry without an id: additional IPs are reported as ADDITIONAL addresses of that public entry instead of forming their own entry. |
| `currentState.networks[].subnetId` | string (uuid) | read-only | Identifier of the subnet this interface draws its fixed address from, or null for an entry without a network id |
| `currentState.powerState` | publicCloud.instance.PowerStateEnum | read-only | Actual administrative power state of the instance as reported by OpenStack (see PowerStateEnum). This may transiently differ from targetSpec.powerState while a power transition is in progress. — one of `ACTIVE`, `PAUSED`, `RESCUE`, `SHELVED`, `SHUTOFF`, `SUSPENDED` |
| `currentState.projectId` | string | read-only | Identifier of the Public Cloud project the instance belongs to |
| `currentState.securityGroups` | publicCloud.securityGroup.SecurityGroupRef[] | read-only | References to the security groups currently attached to the instance's ports |
| `currentState.securityGroups[].id` | string (uuid) | yes | Identifier of the security group |
| `currentState.shares` | publicCloud.instance.InstanceShare[] | read-only | Observed instance-side share attachments. Only populated on a GET of a single instance (never in list responses). Mixing per-share access rules (managed directly on the share resource) with instance-side attach on the same share is unsupported and will show the share OUT_OF_SYNC. See InstanceShare. |
| `currentState.shares[].accessLevel` | publicCloud.storage.file.FileStorageAccessLevelEnum | read-only | Observed access level of the access rule for this instance (see FileStorageAccessLevelEnum: READ_ONLY, READ_WRITE) — one of `READ_ONLY`, `READ_WRITE` |
| `currentState.shares[].accessTo` | string | read-only | The instance IP address the Manila access rule targets. The instance's fixed IPv4 address on the share's network. |
| `currentState.shares[].id` | string (uuid) | read-only | Identifier of the attached file storage (share) |
| `currentState.shares[].state` | publicCloud.storage.file.FileStorageAccessRuleStateEnum | read-only | Observed state of the underlying access rule (see FileStorageAccessRuleStateEnum: ACTIVE, APPLYING, DENYING, ERROR). Null while no state has been reported yet. — one of `ACTIVE`, `APPLYING`, `DENYING`, `ERROR` |
| `currentState.sshKeyName` | string | read-only | Name of the SSH key pair injected into the instance at boot. Null when none was provided. |
| `currentState.userId` | string | read-only | Identifier of the OpenStack user that owns the instance |
| `currentState.volumes` | publicCloud.instance.InstanceVolume[] | read-only | Observed block volumes attached to the instance, with details (name, size). See InstanceVolume. |
| `currentState.volumes[].id` | string (uuid) | read-only | Unique identifier of the attached volume |
| `currentState.volumes[].name` | string | read-only | Display name of the attached volume |
| `currentState.volumes[].size` | integer | read-only | Size of the attached volume in GB |
| `currentTasks` | common.CurrentTask[] | read-only | In-progress operations. Ongoing asynchronous tasks reconciling currentState toward targetSpec, for example a create, resize, reboot, volume attach or share attach. Poll the instance until this list is empty and resourceStatus is READY to know the requested change has been applied. |
| `currentTasks[].errors` | common.TaskError[] | read-only | Errors that occurred on the task |
| `currentTasks[].errors[].message` | string | read-only | Error description |
| `currentTasks[].id` | string (uuid) | read-only | Identifier of the current task |
| `currentTasks[].link` | string | read-only | Link to the task details |
| `currentTasks[].status` | common.CurrentTaskStatusEnum | read-only | Current global status of the current task — one of `ERROR`, `PENDING`, `RUNNING`, `SCHEDULED`, `WAITING_USER_INPUT` |
| `currentTasks[].type` | string | read-only | Type of the current task |
| `id` | string (uuid) | read-only | Unique identifier of the instance |
| `resourceStatus` | common.ResourceStatusEnum | read-only | Resource lifecycle status. High-level readiness of the instance in the system, for example CREATING, READY, UPDATING, DELETING, ERROR. This is distinct from currentState.powerState, which carries the lower-level OpenStack administrative power state of the virtual machine. — one of `CREATING`, `CREATION_PLANNED`, `DELETING`, `ERROR`, `OUT_OF_SYNC`, `READY`, `SUSPENDED`, `UNKNOWN`, `UPDATING` |
| `targetSpec` | publicCloud.instance.InstanceReadTargetSpec | read-only | Desired specification. Last target specification requested for the instance. On update, the difference between the previous and the new targetSpec determines the operations performed (rename, resize, power change, and declarative volume/share attach-detach). |
| `targetSpec.flavor` | publicCloud.instance.InstanceFlavorRef | read-only | Reference to the flavor that sizes the instance (vCPUs, RAM, local disk). Carries only the flavor id. Changing the referenced flavor on PUT triggers a resize of the instance. |
| `targetSpec.flavor.id` | string (uuid) | yes | Identifier of the flavor to size the instance with. Changing it on update triggers a resize. |
| `targetSpec.group` | publicCloud.instance.InstanceGroupRef | read-only | Optional reference to the instance (placement) group the instance is created into, controlling affinity/anti-affinity placement. Immutable: the group is set only at creation time. OpenStack/Nova server groups are immutable. There is no group change on PUT and membership cannot be changed after the instance exists. |
| `targetSpec.group.id` | string (uuid) | yes | Identifier of the instance group. Honored only at creation time. The group cannot be changed afterward. |
| `targetSpec.image` | publicCloud.instance.InstanceImageRef | read-only | Reference to the image the instance boots from. Carries only the image id. Changing the referenced image on PUT triggers a rebuild of the instance from the new image. Null for boot-from-volume instances, which have no backing image. |
| `targetSpec.image.id` | string (uuid) | yes | Identifier of the image to boot from. Changing it on update triggers a rebuild of the instance. |
| `targetSpec.location` | publicCloud.instance.InstanceLocation | read-only | Target location. Region (and optional availability zone) where the instance is provisioned. Immutable after creation. An instance cannot be moved to another region/zone, which is why location is absent from InstanceUpdateTargetSpec. |
| `targetSpec.location.availabilityZone` | string |  | Availability zone within the region where the instance is placed. When omitted at creation the backend selects a zone automatically. Immutable after creation. |
| `targetSpec.location.region` | string | yes | Code of the region where the instance is provisioned, for example GRA11, BHS5. Immutable after creation. An instance cannot be moved to another region. |
| `targetSpec.name` | string | read-only | Desired display name of the instance. Changing it on PUT triggers a rename. |
| `targetSpec.networks` | publicCloud.instance.InstanceNetworkRef[] | read-only | Declarative list of network interfaces the instance is attached to. An entry with a subnetId, and an optional id, is a private interface, optionally carrying an ip to pin its fixed address or to associate an existing floating IP. An entry with autoAssignPublicIp alone requests a public (Ext-Net) interface with a platform-assigned public IP. An entry with ip alone attaches a public IP the project already owns, either an additional IP or an Ext-Net IP of the project in the instance's region. See InstanceNetworkRef. The list drives the desired network topology: adding or removing an entry attaches or detaches the corresponding interface on update. |
| `targetSpec.networks[].autoAssignPublicIp` | boolean |  | Auto-assign public IP. Whether to attach a public (Ext-Net) interface with a public IP assigned by the platform. Only allowed on an entry that has no id, no subnetId and no ip, and at most one entry of the networks list may set it. Requires the optional instance/usePublicIP IAM action. |
| `targetSpec.networks[].id` | string (uuid) |  | Identifier of the private network to attach to. Optional on a private interface: when omitted, the network of subnetId is used. Omit it on an entry declaring public connectivity through autoAssignPublicIp or ip. |
| `targetSpec.networks[].ip` | ip |  | Address of this interface, whose meaning depends on the sibling fields. Without an id and a subnetId: a public IP the project already owns. An additional IP, or an Ext-Net IP of the project in the instance's region. Any other address is rejected, and the entry implicitly attaches the public (Ext-Net) interface. On a private entry (subnetId, with an optional id): pins the interface's fixed address when the address falls inside the subnet CIDR, and otherwise designates an EXISTING floating IP to associate with that interface. A public address requires the optional instance/usePublicIP IAM action. |
| `targetSpec.networks[].subnetId` | string (uuid) |  | Identifier of the subnet the interface draws its fixed address from. Required for a private interface. Leave unset on an entry declaring public connectivity. |
| `targetSpec.powerState` | publicCloud.instance.PowerStateEnum | read-only | Desired administrative power state of the instance (see PowerStateEnum: ACTIVE, PAUSED, RESCUE, SHELVED, SHUTOFF, SUSPENDED). Changing it on PUT drives the corresponding power transition (start, stop, shelve, rescue, pause, suspend). Defaults to ACTIVE. — one of `ACTIVE`, `PAUSED`, `RESCUE`, `SHELVED`, `SHUTOFF`, `SUSPENDED` |
| `targetSpec.securityGroups` | publicCloud.securityGroup.SecurityGroupRef[] | read-only | Optional list of references to the security groups applied to all of the instance's ports. Each entry carries the security group id. Changing this list on PUT re-applies the resulting set of security groups to every instance port. |
| `targetSpec.securityGroups[].id` | string (uuid) | yes | Identifier of the security group |
| `targetSpec.shares` | publicCloud.instance.InstanceShareRef[] | read-only | Declarative list of file storage (shares) attached to the instance, managed exactly like volumes: the diff of this list on PUT drives attach/detach. Attaching a share creates a Manila IP access rule for the instance's interface on the share's network. The instance must have an interface on that network or the operation errors. Detaching (removing an entry from this list) deletes the matching access rule and is idempotent. Each entry's accessLevel defaults to READ_WRITE when omitted (see InstanceShareRef). |
| `targetSpec.shares[].accessLevel` | publicCloud.storage.file.FileStorageAccessLevelEnum |  | Desired access level granted to the instance for this share (see FileStorageAccessLevelEnum: READ_ONLY, READ_WRITE). Defaults to READ_WRITE. — one of `READ_ONLY`, `READ_WRITE` |
| `targetSpec.shares[].id` | string (uuid) | yes | Identifier of the file storage (share) to attach. Adding this reference attaches the share to the instance. Removing it from the shares list detaches it. |
| `targetSpec.sshKeyName` | string | read-only | Name of the SSH key pair injected into the instance at boot for initial access. Immutable / create-only: the key is injected once during provisioning and cannot be changed afterward, which is why sshKeyName is absent from InstanceUpdateTargetSpec. |
| `targetSpec.volumes` | publicCloud.instance.InstanceVolumeRef[] | read-only | Declarative list of block volumes attached to the instance, each referencing a volume by id (see InstanceVolumeRef). Attach/detach is driven by diffing this list on PUT. There is no imperative attach/detach sub-route. Adding a volume reference attaches that volume. Removing one detaches it. |
| `targetSpec.volumes[].id` | string (uuid) | yes | Identifier of the volume to attach. Adding this reference attaches the volume. Removing it from the volumes list detaches it. |
| `updatedAt` | string (date-time) | read-only | Last modification date of the instance, as an ISO 8601 / RFC 3339 timestamp |

```json
{
  "checksum": "string",
  "createdAt": "2024-01-01T12:00:00Z",
  "currentState": {
    "availableActions": [
      {
        "available": true,
        "name": "LOCK"
      }
    ],
    "flavor": {
      "bandwidth": {
        "private": 0,
        "publicInbound": 0,
        "publicOutbound": 0
      },
      "disk": 0,
      "gpus": 0,
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "string",
      "ram": 0,
      "vcpus": 0
    },
    "group": {
      "id": "00000000-0000-0000-0000-000000000000"
    },
    "hostId": "string",
    "image": {
      "defaultUser": "string",
      "deprecated": true,
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "string",
      "size": 0,
      "status": "ACTIVE"
    },
    "location": {
      "availabilityZone": "string",
      "region": "string"
    },
    "locked": true,
    "name": "string",
    "networks": [
      {
        "addresses": [
          {
            "ip": "192.0.2.0",
            "mac": "00:00:5e:00:53:01",
            "type": "ADDITIONAL",
            "version": 0
          }
        ],
        "gatewayId": "00000000-0000-0000-0000-000000000000",
        "id": "00000000-0000-0000-0000-000000000000",
        "subnetId": "00000000-0000-0000-0000-000000000000"
      }
    ],
    "powerState": "ACTIVE",
    "projectId": "string",
    "securityGroups": [
      {
        "id": "00000000-0000-0000-0000-000000000000"
      }
    ],
    "shares": [
      {
        "accessLevel": "READ_ONLY",
        "accessTo": "string",
        "id": "00000000-0000-0000-0000-000000000000",
  …
```

### Example

```bash
curl -X PUT \
  "https://api.eu.ovhcloud.com/v2/publicCloud/project/{projectId}/compute/instance/{instanceId}" \
  -H "accept: application/json" \
  -H "authorization: Bearer $OVH_TOKEN" \
  -H "content-type: application/json" \
  -d '{ }'
```

```python
'''
First, install the latest release of Python wrapper: $ pip install ovh
'''
import json
import ovh

# Instantiate an OVH Client.
# You can generate new credentials with full access to your account on
# the token creation page (https://api.ovh.com/createToken/index.cgi?GET=/*&PUT=/*&POST=/*&DELETE=/*)
client = ovh.Client(
	endpoint='ovh-eu',               # Endpoint of API OVH (List of available endpoints: https://github.com/ovh/python-ovh#2-configure-your-application)
	application_key='xxxxxxxxxx',    # Application Key
	application_secret='xxxxxxxxxx', # Application Secret
	consumer_key='xxxxxxxxxx',       # Consumer Key
)

# Request body type: publicCloud.instance.InstanceUpdate
result = client.put("/v2/publicCloud/project/{projectId}/compute/instance/{instanceId}",
	checksum = None, # Concurrency-control checksum. Optional checksum obtained from the last GET of the instance. When supplied, it must still match the instance's current checksum or the update is rejected with a 409 checksum-mismatch conflict, protecting against a concurrent modification. When omitted or empty, the concurrency check is skipped and the update is forced (last-write-wins). (type: string, nullable)
	targetSpec = None, # Desired specification (mutable fields). Updated target specification restricted to the fields that can change after creation. Immutable fields (location, sshKeyName, placement group) are intentionally absent. See InstanceUpdateTargetSpec. userData is write-only (never echoed back) and follows tri-state semantics. Changing it (clearing or replacing) reinstalls the instance. (type: publicCloud.instance.InstanceUpdateTargetSpec)
)

# Pretty print
print(json.dumps(result, indent=4))
```

```php
<?php
/**
 * First, download the latest release of PHP wrapper on github
 * And include this script into the folder with extracted files
 */
require __DIR__ . '/vendor/autoload.php';
use \Ovh\Api;

/**
 * Instantiate an OVH Client.
 * You can generate new credentials with full access to your account on
 * the token creation page (https://api.ovh.com/createToken/index.cgi?GET=/*&PUT=/*&POST=/*&DELETE=/*)
 */
$ovh = new Api('xxxxxxxxxx',  // Application Key
               'xxxxxxxxxx',  // Application Secret
               'ovh-eu',      // Endpoint of API OVH (List of available endpoints: https://github.com/ovh/python-ovh#2-configure-your-application)
               'xxxxxxxxxx'); // Consumer Key

// Request body type: publicCloud.instance.InstanceUpdate
$result = $ovh->put("/v2/publicCloud/project/{projectId}/compute/instance/{instanceId}", array(
	checksum => null, // Concurrency-control checksum. Optional checksum obtained from the last GET of the instance. When supplied, it must still match the instance's current checksum or the update is rejected with a 409 checksum-mismatch conflict, protecting against a concurrent modification. When omitted or empty, the concurrency check is skipped and the update is forced (last-write-wins). (type: string, nullable)
	targetSpec => null, // Desired specification (mutable fields). Updated target specification restricted to the fields that can change after creation. Immutable fields (location, sshKeyName, placement group) are intentionally absent. See InstanceUpdateTargetSpec. userData is write-only (never echoed back) and follows tri-state semantics. Changing it (clearing or replacing) reinstalls the instance. (type: publicCloud.instance.InstanceUpdateTargetSpec)
));

print_r($result);
?>
```