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

# List and Get Instances

> List all API-created instances, get detailed instance information, and delete instances

## List Instances

Retrieve all Ubuntu VPS instances created through the API for your account. A server made with one key shows for every key of the account.

```
GET /api/v1/instances
```

### Example Request

```bash
curl https://repocloud.io/api/v1/instances \
  -H "Authorization: Bearer rcmcp_your_key_here"
```

### Response (200 OK)

Returns an array of instance objects, sorted by creation date (newest first). The list serves the stored root password and never asks the control plane for it; the detail answer reads the current one.

```json
[
  {
    "instance_id": 456,
    "vps_id": "vps-a1b2c3",
    "status": "Online",
    "ipv4": "203.0.113.42",
    "domain": "vps-a1b2c3.vps.rcld.dev",
    "custom_domain": null,
    "root_user": "root",
    "root_password": "generated-password-here",
    "ssh_port": 22,
    "project_name": "my-dev-server",
    "plan": {
      "flavor": "s-2vcpu-4gb",
      "vcpu": 2,
      "ram_mb": 4096,
      "disk_gb": 40,
      "hourly_price": 0.0167
    },
    "created_at": "2026-07-15T10:30:00"
  }
]
```

The `created_at` time is UTC with no zone suffix.

> [!NOTE]
>
> This endpoint only returns instances created through the API (those with an associated API key). A server deployed through the web dashboard or AI Deploy is not included, answers 404 on every API route, and is managed in the dashboard.

### Instance Statuses

The list shows RepoCloud's own words for a server:

| Status | Meaning |
|--------|---------|
| `Deploying` | Instance is being provisioned. A new server is stored and listed as `Deploying`; the detail answer also falls back to this word when the control plane cannot be read |
| `Online` | Instance is running and accessible |
| `Paused` | Instance has been powered off or billing-paused. The word follows a power-off after the next 2-minute check, not instantly, and a powered-off server is still billed at the full price of its tier |
| `Error` | The control plane reports the server as failed, being deleted, or gone, or does not know it any more |

A destroyed server never shows a status: it leaves the list and answers 404.

---

## Get Instance Detail

Retrieve detailed information about a specific instance, including live status from the control plane.

```
GET /api/v1/instances/{instance_id}
```

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `instance_id` | integer | The instance ID returned at deploy time |

### Example Request

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

### Response (200 OK)

The detail endpoint fetches live information from the control plane. The fields `status`, `custom_domain`, and `activated_at` come from there and use the control plane's own words, so a running server reads `active`, not `Online`. This is also the answer that carries the current root password.

```json
{
  "instance_id": 456,
  "vps_id": "vps-a1b2c3",
  "status": "active",
  "ipv4": "203.0.113.42",
  "domain": "vps-a1b2c3.vps.rcld.dev",
  "custom_domain": null,
  "root_user": "root",
  "root_password": "generated-password-here",
  "ssh_port": 22,
  "project_name": "my-dev-server",
  "plan": {
    "flavor": "s-2vcpu-4gb",
    "vcpu": 2,
    "ram_mb": 4096,
    "disk_gb": 40,
    "hourly_price": 0.0167
  },
  "activated_at": "2026-07-15T10:35:00+00:00",
  "created_at": "2026-07-15T10:30:00"
}
```

The `activated_at` time is the control plane's own, with a `+00:00` suffix, and is `null` until the server is `active`; `created_at` is RepoCloud's UTC time with no suffix.

When the control plane cannot be read, the call still answers 200, with RepoCloud's stored word in `status` (`Deploying`, `Online`, and so on) and `null` in `custom_domain` and `activated_at`.

### Control Plane Statuses

| Status | Meaning |
|--------|---------|
| `pending` | Instance creation has been requested |
| `provisioning` | Instance is being provisioned |
| `active` | Instance is running |
| `stopped` | Instance is powered off |
| `failed` | The deployment failed |

The control plane has six more words — `resizing`, `restoring`, `moving`, `deleting`, `destroyed`, and `quarantined` — for the operations and states those names describe.

### Error Responses

| Status | Error | Cause |
|--------|-------|-------|
| 404 | `Instance not found` | Instance does not exist, belongs to another user, was not created via the API, or was removed after a failed deployment |

---

## Delete Instance

Permanently destroy a VPS instance and release its IPv4 address. The SSH key that RepoCloud generated for the server is deleted with it; a key you supplied stays.

```
DELETE /api/v1/instances/{instance_id}
```

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `instance_id` | integer | The instance ID to delete |

### Example Request

```bash
curl -X DELETE https://repocloud.io/api/v1/instances/456 \
  -H "Authorization: Bearer rcmcp_your_key_here"
```

### Response (200 OK)

```json
{
  "instance_id": 456,
  "status": "deleting",
  "job_id": "3f2a9c1e-8b47-4d6a-9e35-1c7b5a2f0d84"
}
```

The `job_id` is a text identifier of the deletion job, and is `null` when the control plane no longer knew the server. No call that takes an API key reads a job, and the instance is removed from your account immediately, so there is nothing to poll.

> [!WARNING]
>
> Deletion is irreversible. All data on the server, including snapshots, is permanently removed.

### Error Responses

| Status | Error | Cause |
|--------|-------|-------|
| 404 | `Instance not found` | Instance does not exist, belongs to another user, or was not created via the API. A second delete of the same server answers 404 too |
| 502 | `Failed to destroy instance` | The control plane returned an error, and the answer carries a `detail` text. The instance may still exist, and you can repeat the call; a 404 from the control plane counts as success |