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

# Instance Actions

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

## Execute an Action

Perform a power or resize action on a running VPS instance.

```
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`                             |
| `flavor` | string | Only for `resize` | The new flavor ID to resize to (see [Available Flavors](/api/deploy#available-flavors)) |

### Response (200 OK)

```json theme={null}
{
  "ok": true,
  "action": "power_on",
  "job_id": "job-abc123"
}
```

The `job_id` can be used to track the action's progress.

***

## Action Types

### Power On

Start a powered-off instance.

```bash theme={null}
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 the instance was billing-paused (system-paused due to zero balance), you must add funds before powering on.
</Note>

### Power Off

Gracefully shut down a running instance.

```bash theme={null}
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"}'
```

Powering off an instance marks it as user-paused. Paused instances are billed at 25% of the normal hourly rate.

### Reboot

Restart a running instance.

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

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

## Billing-Paused Lockdown

When an instance is system-paused due to zero balance (billing-paused), the following actions are blocked:

| Action      | Blocked? | How to Unlock                     |
| ----------- | -------- | --------------------------------- |
| `power_on`  | Yes      | Add funds (balance must be > \$0) |
| `reboot`    | Yes      | Add funds                         |
| `resize`    | Yes      | Add funds                         |
| `power_off` | No       | Always allowed                    |

The API returns HTTP 403 with `"Instance is billing-paused"` for blocked actions.

## Error Responses

| Status | Error                                   | Cause                                                                            |
| ------ | --------------------------------------- | -------------------------------------------------------------------------------- |
| 400    | `Invalid action type`                   | `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                                                 |
| 400    | `Flavor xxx is permanently unavailable` | The `s-1vcpu-1gb` flavor cannot be used                                          |
| 402    | `Insufficient balance to power on`      | Balance is \$0 or less                                                           |
| 403    | `Instance is billing-paused`            | Instance is system-paused; add funds to unlock                                   |
| 404    | `Instance not found`                    | Instance does not exist, belongs to another user, or was not created via the API |
| 503    | `Tier capacity exhausted`               | No capacity for the target resize flavor                                         |
| 502    | `Upstream error`                        | Control plane returned an error                                                  |