> For the complete documentation index, see [llms.txt](https://docs.nebulablock.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nebulablock.com/api-reference/platform-api/list-products/create-instance.md).

# Create Instance

Deploy a new GPU or CPU instance with your chosen hardware, OS image, and SSH key.

Create an instance with the specified custom configuration and features provided in the request body.

## HTTP Request

`POST` `{API_URL}/computing/instance`

## Body parameters

| Parameter       | Requirement | Type     | Description                                                                                                                                   |
| --------------- | ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `instance_name` | Required    | `string` | Name for the instance. Letters, digits, `.` and `-` only — the pattern `^[a-zA-Z0-9.-]+$` is enforced, so spaces and underscores are rejected |
| `product_id`    | Required    | `string` | The hardware configuration to deploy, from [List Products](/api-reference/platform-api/list-products.md)                                      |
| `image_id`      | Required    | `string` | The OS image to install, from [List OS Images](/api-reference/platform-api/list-products/list-os-images.md)                                   |
| `ssh_key_id`    | Required    | `string` | UUID of the SSH key to authorise, from [List SSH Keys](/api-reference/platform-api/list-ssh-keys.md)                                          |
| `port_list`     | Optional    | `list`   | Ports to expose. Container deployments only                                                                                                   |
| `env`           | Optional    | `object` | Environment variables as string key/value pairs. Container deployments only                                                                   |
| `cmd`           | Optional    | `string` | Command to run in the container. Container deployments only                                                                                   |

> **Important:** `ssh_key_id` must be the SSH key's **UUID string**, not its numeric row id. Body validation failures — a numeric `ssh_key_id`, or an `instance_name` that breaks the pattern — are rejected with **HTTP 422** before the request reaches the deploy logic. They are the only real HTTP errors here; every other failure below comes back as HTTP 200.

> **Important:** `ssh_key_id` is required for every deployment. Leaving it out returns **HTTP 200** with `"status": "failed"` and the message `"SSH Key not found"`; no instance is created.

> **Note:** `image_id` and `product_id` must come from the same data center — match on `dc_id`. Do **not** try to match their `region` strings: the two endpoints do not phrase regions the same way, and a product in region `CANADA` is routinely deployed with an image whose region reads `CANADA-1`, as in the example below.

> **Important:** The ids in the example below are **illustrative — do not copy them**. Fetch current ones from [List Products](/api-reference/platform-api/list-products.md) and [List OS Images](/api-reference/platform-api/list-products/list-os-images.md) at the time you deploy. Capacity moves constantly: a configuration that is available today can be gone tomorrow, and deploying one whose `is_available` is `false` returns `"This configuration is currently out of stock. Please choose another or try again later."`

> **Note:** `port_list`, `env` and `cmd` apply to container deployments and are ignored for virtual machines and bare metal.

## Response Attributes

#### message `string`

A description of the status of the request.

#### status `string`

Indicates the result of the request. **success** signifies success, while **failed** indicates an error.

> **Important:** A rejected deployment still returns **HTTP 200**. Read `status`, not the HTTP code. `message` carries the reason, for example `"SSH Key not found"`, `"Product not found"`, `"This configuration is currently out of stock. Please choose another or try again later."`, or `"Insufficient balance to start the instance. Please add credits to your account and try again."`.

> **Note:** A `success` response means the instance was accepted for deployment, not that it is ready. It passes through a provisioning status — `Created`, `Deploying` or `Provisioning`, depending on the configuration — before reaching `Running`, and fast configurations can report `Running` straight away. Poll [Get Instance](/api-reference/platform-api/list-products/get-instance.md) for the current status rather than assuming any particular starting value.

## Example

#### Request

```bash
curl -X POST '{API_URL}/computing/instance' \
-H 'Authorization: Bearer {TOKEN/KEY}' \
-H 'Content-Type: application/json' \
-d '{
    "instance_name":"testname",
    "product_id":"b59cfc9f-8ab0-447f-8b2a-bb54e529d986",
    "image_id":"79f79270-656a-4a30-be43-9a884b43b7ea",
    "ssh_key_id":"a3f1c2d4-5b6e-7f80-9a1b-2c3d4e5f6a7b"
}'
```

#### Response

```json
{
    "message": "Instance created successfully",
    "status": "success"
}

```