API and MCP

Instance Actions

Power on, power off, reboot, and resize VPS instances through the API

Execute an Action

Perform a power or resize action on one of your API-created servers. A server made in the dashboard answers 404.

POST /api/v1/instances/{instance_id}/actions

Path Parameters

Parameter	Type	Description
`instance_id`	integer	The instance ID to act on

Request Body

Field	Type	Required	Description
`type`	string	Yes	Action type: `power_on`, `power_off`, `reboot`, or `resize`. The field is named `type`: a body that names it `action` (the name the answer uses) is refused with a 400
`flavor`	string	Only for `resize`	The new flavor ID to resize to (see Available Flavors)

Response (200 OK)

json

{
  "ok": true,
  "action": "power_on",
  "job_id": "3f2a9c1e-8b47-4d6a-9e35-1c7b5a2f0d84"
}

No call that takes an API key reads a job, so the job_id is not something to poll. Follow the effect by reading the instance’s status with Get Instance Detail: stopped once a power off has finished, active once a power on has finished, and resizing while a resize runs.

Action Types

Power On

Start a powered-off instance.

bash

curl -X POST https://repocloud.io/api/v1/instances/456/actions \
  -H "Authorization: Bearer rcmcp_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"type": "power_on"}'

Power on requires a positive account balance (greater than $0). If RepoCloud paused the instance for a zero balance (billing-paused), you must add funds before powering on. RepoCloud also powers such a server on again by itself once your balance is above zero, so after paying, the call is often unnecessary.

Power Off

Power off a running instance.

bash

curl -X POST https://repocloud.io/api/v1/instances/456/actions \
  -H "Authorization: Bearer rcmcp_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"type": "power_off"}'

A powered-off server keeps its disk and its IPv4 address, so it is still billed at the full hourly rate. The dashboard shows it as Paused after the next 2-minute check.

Reboot

Restart a running instance.

bash

curl -X POST https://repocloud.io/api/v1/instances/456/actions \
  -H "Authorization: Bearer rcmcp_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"type": "reboot"}'

Resize

Change the instance to a different resource tier. The new tier is recorded on your account when the call is accepted, so the next hourly charge uses its price.

bash

curl -X POST https://repocloud.io/api/v1/instances/456/actions \
  -H "Authorization: Bearer rcmcp_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"type": "resize", "flavor": "s-4vcpu-8gb"}'

Disk downgrades are not possible. You can only resize to a flavor with equal or larger disk allocation. For example, if your instance is on s-2vcpu-4gb (40 GB disk), you cannot resize to s-1vcpu-2gb (30 GB disk). Two tiers with the same disk can be swapped in both directions: Tier 3 (s-2vcpu-2gb) and Tier 4 (s-2vcpu-4gb) both have 40 GB, so you can move between them to get more RAM or less.

Billing-Paused Lockdown

When RepoCloud pauses an instance for a zero balance (billing-paused), the following actions are blocked:

Action	Blocked?	Answer	How to Unlock
`power_on`	Yes	402 `Insufficient balance to power on`	Add funds (balance must be above $0)
`reboot`	Yes	403 `Instance is billing-paused`	Add funds
`resize`	Yes	403 `Instance is billing-paused`	Add funds
`power_off`	No	—	Always allowed

Only reboot and resize answer 403 with "Instance is billing-paused". A power_on answers 402, because a billing-paused server always has a balance of zero or less.

Error Responses

Status	Error	Cause
400	`Invalid action type. Must be one of: power_on, power_off, reboot, resize`	`type` is not one of the four valid actions
400	`flavor is required for resize`	Resize action without a `flavor` field
400	`Invalid flavor: xxx`	Unrecognized flavor ID
400	`Already on this flavor`	Trying to resize to the current flavor
400	`Cannot downgrade disk size`	Target flavor has a smaller disk. The answer’s `detail` reads “Downgrades are not possible because the disk cannot be shrunk.” A resize to `s-1vcpu-1gb` ends here too
400	`Bad request`	The VPS control plane refused the action; `detail` repeats its reason
400	`Instance has no VPS backend ID`	The server has no control plane id
402	`Insufficient balance to power on`	Balance is $0 or less
403	`Instance is billing-paused`	`reboot` or `resize` on a billing-paused instance; add funds to unlock
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
409	`Conflict`	The VPS control plane reports a conflict, for example a resize that arrives while the server is busy; `detail` repeats its reason
500	`Internal server error`	An unexpected fault
502	`Upstream error`	The VPS control plane answered with any other error status
503	`Tier capacity exhausted`	No capacity for the target resize flavor; `detail` carries the text of the capacity check

Get started for free