> ## Documentation Index
> Fetch the complete documentation index at: https://docs.repocloud.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy Instances

> Deploy new Ubuntu VPS instances via the API

## Deploy a New Instance

<Note>
  The API deploys **Ubuntu VPS instances only**. For other VPS templates (Coolify, Dokploy, etc.), use [AI Deploy](/deployment/ai-deploy) or the web dashboard.
</Note>

```
POST /api/v1/instances
```

### Request Body

| Field            | Type   | Required | Description                                                                                               |
| ---------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------- |
| `project_name`   | string | Yes      | A name for your instance (max 64 characters)                                                              |
| `flavor`         | string | Yes      | The server size flavor ID (see [Available Flavors](#available-flavors))                                   |
| `ssh_public_key` | string | No       | Your SSH public key. If omitted, a key pair is generated and the private key is returned in the response. |

### Example Request

```bash theme={null}
curl -X POST https://repocloud.io/api/v1/instances \
  -H "Authorization: Bearer rcmcp_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "project_name": "my-dev-server",
    "flavor": "s-2vcpu-4gb",
    "ssh_public_key": "ssh-ed25519 AAAA... user@host"
  }'
```

### Response (202 Accepted)

The instance is created asynchronously. The response includes connection credentials and a `status` field that starts as `pending`.

```json theme={null}
{
  "instance_id": 456,
  "vps_id": "inst-abc123",
  "status": "pending",
  "ipv4": "203.0.113.42",
  "domain": "abcd1234.rpcld.co",
  "custom_domain": null,
  "root_user": "root",
  "root_password": "generated-password-here",
  "ssh_port": 22,
  "ssh_key": {
    "name": "mcp-key-456",
    "fingerprint": "SHA256:xxxx...",
    "public_key": "ssh-ed25519 AAAA...",
    "private_key": "-----BEGIN OPENSSH PRIVATE KEY-----\n..."
  },
  "plan": {
    "flavor": "s-2vcpu-4gb",
    "vcpu": 2,
    "ram_mb": 4096,
    "disk_gb": 40,
    "hourly_price": 0.0167
  },
  "created_at": "2026-07-15T10:30:00"
}
```

<Note>
  The `ssh_key.private_key` field is only included when you do **not** provide your own `ssh_public_key`. Store it securely — it is not retrievable later.
</Note>

### Polling for Readiness

After deploying, poll the [instance detail endpoint](/api/instances#get-instance-detail) until `status` changes from `pending`/`Deploying` to `Online`:

```bash theme={null}
curl https://repocloud.io/api/v1/instances/456 \
  -H "Authorization: Bearer rcmcp_your_key_here"
```

Typical provisioning takes 2–5 minutes. Once `status` is `Online` and `ipv4` is populated, the server is ready for SSH connections.

## Available Flavors

| Flavor ID       | vCPU | RAM   | SSD    | Hourly   | Monthly |
| --------------- | ---- | ----- | ------ | -------- | ------- |
| `s-1vcpu-2gb`   | 1    | 2 GB  | 30 GB  | \$0.0083 | \$6.00  |
| `s-2vcpu-2gb`   | 2    | 2 GB  | 40 GB  | \$0.0125 | \$9.00  |
| `s-2vcpu-4gb`   | 2    | 4 GB  | 40 GB  | \$0.0167 | \$12.00 |
| `s-4vcpu-8gb`   | 4    | 8 GB  | 80 GB  | \$0.0333 | \$24.00 |
| `s-8vcpu-16gb`  | 8    | 16 GB | 160 GB | \$0.0667 | \$48.00 |
| `s-16vcpu-32gb` | 16   | 32 GB | 320 GB | \$0.1333 | \$96.00 |

<Warning>
  The `s-1vcpu-1gb` flavor (\$3/month) is **not available** for VPS instances. It is reserved for Container Apps only.
</Warning>

## Error Responses

| Status | Error                                                  | Cause                                                                                |
| ------ | ------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| 400    | `project_name is required`                             | Missing or empty `project_name`                                                      |
| 400    | `project_name must be 64 characters or fewer`          | Name exceeds 64 characters                                                           |
| 400    | `flavor is required`                                   | Missing or empty `flavor`                                                            |
| 400    | `Invalid flavor: xxx`                                  | Unrecognized flavor ID, or elastic/premium flavor                                    |
| 400    | `Flavor xxx is permanently unavailable for Ubuntu VPS` | The `s-1vcpu-1gb` flavor cannot be used for VPS                                      |
| 402    | `Insufficient balance`                                 | Account balance is \$3 or less. Deposit at [/billing](https://repocloud.io/billing). |
| 503    | `VPS capacity exhausted`                               | No IPv4 addresses are currently available                                            |
| 503    | `Tier capacity exhausted`                              | The selected flavor has no available capacity                                        |
| 502    | `Upstream error`                                       | The VPS control plane returned an error — retry after a few seconds                  |

## Connecting to Your Instance

Once the instance status is `Online`:

```bash theme={null}
ssh root@203.0.113.42
```

Use the root password from the deploy response, or the SSH key you provided/received.