List and Get 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

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.

[
  {
    "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.

Instance Statuses

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

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

Example Request

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.

{
  "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

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

Error Responses

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

Example Request

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

Response (200 OK)

{
  "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.

Error Responses