---
description: >-
  Documentation for the plugin's API, which can be used to create custom
  controls etc. in other services.
---

# 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`) |
