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

# 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](https://repocloud.io/docs/api/deploy.md#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](https://repocloud.io/docs/api/instances.md#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"}'
```

> [!NOTE]
>
> 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"}'
```

> [!WARNING]
>
> 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 |