List and Get Instances - RepoCloud Documentation

List Instances

Retrieve all Ubuntu VPS instances created through the API for your 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).

[
  {
    "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"
  }
]

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.

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

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

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

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": "job-xyz789"
}

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

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
502	`Failed to destroy instance`	The control plane returned an error — the instance may still exist

​List Instances

​Example Request

​Response (200 OK)

​Instance Statuses

​Get Instance Detail

​Path Parameters

​Example Request

​Response (200 OK)

​Error Responses

​Delete Instance

​Path Parameters

​Example Request

​Response (200 OK)

​Error Responses

List Instances

Example Request

Response (200 OK)

Instance Statuses

Get Instance Detail

Path Parameters

Example Request

Response (200 OK)

Error Responses

Delete Instance

Path Parameters

Example Request

Response (200 OK)

Error Responses