> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/knowledge-base/automation-api/force-power-off-vm-using-api.md).

# Force Power Off a VM Using the API

Step-by-step instructions for force powering off a non-responsive VM using the VergeOS API and Swagger interface, including how to locate the VM ID, verify status, and issue the power-off command.

## Overview

{% hint style="info" %}
**Key Points**

* Use the VergeOS API to force power off a stuck VM
* Requires API/Swagger access
* Process involves multiple API calls to ensure accurate targeting
* Should only be used when normal power off methods fail
  {% endhint %}

This guide explains how to force power off a non-responsive virtual machine (VM) using the VergeOS API when standard power-off methods are unsuccessful.

## Prerequisites

* Access to the VergeOS UI with administrative privileges
* The name of the stuck/non-responsive VM
* Basic understanding of API operations

{% hint style="warning" %}
**Important**

This procedure should only be used when standard power-off methods have failed. Forcing a VM to power off can lead to data loss or corruption if not used carefully.
{% endhint %}

## Steps

### 1. Access the API Documentation

1. Navigate to **System** in the VergeOS UI
2. Click on **API Documentation** (also known as Swagger)

### 2. Locate the VM ID

1. In the API interface, locate and expand the **VMs** table
2. Click the blue **GET** button
3. In the parameters section:
   * Use filter `name eq your_vm_name` to find a specific VM
4. Click **Execute**
5. Note the `Machine` number from the response

### 3. Get Machine Status ID

1. Navigate to the **machines** table
2. Click the blue **GEt /machines/{id}**
3. In the parameters:
   * Set `id` to the `Machine number from the previous response`
   * Set `fields` to `status`
4. Click **Execute**
5. From the response, note the `status` value

### 4. Verify Machine Status

1. Go to the **machine\_status** table
2. Click the blue **GET /machine\_stats/{id}**
3. In the parameters:
   * Set `id` to `status_number` (using the status value from step 3)
   * Set `fields` to `most`
4. Click **Execute**
5. Verify this is the correct VM by checking:
   * Number of cores
   * RAM allocation
   * Status information
   * Machine number

### 5. Force Power Off

1. In the **machine\_status** table, click **PUT**
2. Enter the status number as the `id` **resource id**
3. In the request body, enter the following JSON:

```json
{
    "running": false,
    "migratable": true,
    "status": "stopped",
    "state": "offline"
}
```

4. Click **Execute**

### 6. Verify Power Off

1. Return to the VergeOS UI
2. Verify that the VM shows as powered off

## Troubleshooting

{% hint style="warning" %}
**Common Issues**

* If the VM doesn't show as powered off after the API call, wait a few minutes for the status to update
* If the status doesn't update, verify that all IDs were correct in the previous steps
* In case of errors, check the API response for specific error messages
  {% endhint %}

## Additional Notes

* Always document the VM's ID and status values before making changes
* Consider taking a snapshot of the VM before forcing power off if possible
* Monitor the VM after forcing power off to ensure it starts properly when needed

***

## Feedback

{% hint style="info" %}
**Need Help?**

If you do not feel confortable with this process, please reach out to our support team for assistance.
{% endhint %}

***

{% hint style="info" %}
**Document Information**

* Last Updated: 2024-01-28
* VergeOS Version: All
  {% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.verge.io/knowledge-base/automation-api/force-power-off-vm-using-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.