> ## 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.

# 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.

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

### Example Request

```bash theme={null}
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).

```json theme={null}
[
  {
    "instance_id": 456,
    "vps_id": "inst-abc123",
    "status": "Online",
    "ipv4": "203.0.113.42",
    "domain": "abcd1234.rpcld.co",
    "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"
  }
]
```

<Note>
  This endpoint only returns instances created through the API (those with an associated API key). Instances deployed through the web dashboard or AI Deploy are not included.
</Note>

### Instance Statuses

| Status      | Meaning                                         |
| ----------- | ----------------------------------------------- |
| `pending`   | Instance creation has been requested            |
| `Deploying` | Instance is being provisioned                   |
| `Online`    | Instance is running and accessible              |
| `Paused`    | Instance has been powered off or billing-paused |
| `Deleted`   | Instance has been destroyed                     |

***

## 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 theme={null}
curl https://repocloud.io/api/v1/instances/456 \
  -H "Authorization: Bearer rcmcp_your_key_here"
```

### Response (200 OK)

The detail endpoint fetches live status from the control plane, so `status` reflects the current server state (not just the last-known DB state).

```json theme={null}
{
  "instance_id": 456,
  "vps_id": "inst-abc123",
  "status": "Online",
  "ipv4": "203.0.113.42",
  "domain": "abcd1234.rpcld.co",
  "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",
  "created_at": "2026-07-15T10:30:00"
}
```

### Error Responses

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

***

## Delete Instance

Permanently destroy a VPS instance and release its IPv4 address.

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

### Path Parameters

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

### Example Request

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

### Response (200 OK)

```json theme={null}
{
  "instance_id": 456,
  "status": "deleting",
  "job_id": "job-xyz789"
}
```

The `job_id` can be used to track deletion progress if needed. The instance is removed from the database immediately.

<Warning>
  Deletion is irreversible. All data on the server, including snapshots, is permanently removed.
</Warning>

### Error Responses

| Status | Error                        | Cause                                                                            |
| ------ | ---------------------------- | -------------------------------------------------------------------------------- |
| 404    | `Instance not found`         | Instance does not exist, belongs to another user, or was not created via the API |
| 502    | `Failed to destroy instance` | The control plane returned an error — the instance may still exist               |