# REST API

The plugin implements a [SimpleAPI as provided by OctoPrint](https://docs.octoprint.org/en/devel/plugins/mixins.html#simpleapiplugin), which enables external access to the plugin's functionality.

It has a single endpoint, supporting a get request and posting a command.

## SimpleAPI Get

<mark style="color:blue;">`GET`</mark> `http://octopi.local/api/plugin/ws281x_led_status`

Get current state of the plugin, which includes the light status and the torch status.

#### Headers

| Name                                        | Type   | Description                |
| ------------------------------------------- | ------ | -------------------------- |
| X-Api-Key<mark style="color:red;">\*</mark> | string | A valid OctoPrint API key. |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "lights_on": false,
  "torch_on": false
}
```

{% endtab %}
{% endtabs %}

## SimpleAPI Command

<mark style="color:green;">`POST`</mark> `http://octopi.local/api/plugin/ws281x_led_status`

Send commands to the plugin, to make it do something.

#### Headers

| Name                                        | Type   | Description               |
| ------------------------------------------- | ------ | ------------------------- |
| X-Api-Key<mark style="color:red;">\*</mark> | string | A valid OctoPrint API key |

#### Request Body

| Name                                      | Type   | Description                                               |
| ----------------------------------------- | ------ | --------------------------------------------------------- |
| command<mark style="color:red;">\*</mark> | string | The command to be sent to the plugin. See commands below. |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "lights_on": false,
  "torch_on": false
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
See also the OctoPrint [SimpleApi docs](https://docs.octoprint.org/en/devel/plugins/mixins.html#octoprint.plugin.SimpleApiPlugin) for details about how the request should be structured.
{% endhint %}

## Commands

| Command          | Parameters | Explanation                                                                                            |
| ---------------- | ---------- | ------------------------------------------------------------------------------------------------------ |
| `lights_on`      | None       | Turn the LEDs on                                                                                       |
| `lights_off`     | None       | Turn the LEDs off                                                                                      |
| `lights_toggle`  | None       | Toggle the LED state                                                                                   |
| `torch_on`       | None       | Turn the torch mode on                                                                                 |
| `torch_off`      | None       | Turn the torch mode off. Only available if torch mode is configured as toggle.                         |
| `test_os_config` | None       | Begin an OS configuration test. Asynchronous, data is returned on the socket                           |
| `test_led`       | `color`    | Set the LEDs to the configured HTML RGB colour, color should be a full 7 character hex (eg. `#ff00ff`) |


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://cp2004.gitbook.io/ws281x-led-status/documentation/rest-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.