Skip to content

Add JSON API documentation for palettes #317

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mik-laj wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add JSON API documentation for palettes #317

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
858e704
Add JSON API documentation for palettes
mik-laj May 9, 2026
5283cc8
Revise palette ID descriptions in JSON API
mik-laj May 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 52 additions & 1 deletion docs/interfaces/json-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -196,7 +196,7 @@ c3 | 0 to 31 | Effect custom slider 3.
o1 | bool | Effect option 1. Custom options are hidden or displayed and labeled based on [effect metadata](#effect-metadata).
o2 | bool | Effect option 2.
o3 | bool | Effect option 3.
pal | 0 to info.palcount -1 | ID of the color palette or ~ to increment, ~- to decrement, or r for random.
pal | byte | ID of an available palette (see [Palettes](#palettes) section for available ID ranges depending on firmware version) or ~ to increment, ~- to decrement, or r for random.

@coderabbitai coderabbitai Bot May 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix table row pipe style for the pal field entry.

This changed row is missing the leading |, which triggers MD055 and can fail docs linting.

Suggested fix 
-pal | byte | ID of an available palette (see [Palettes](`#palettes`) section for available ID ranges depending on firmware version) or ~ to increment, ~- to decrement, or r for random.
+| pal | byte | ID of an available palette (see [Palettes](`#palettes`) section for available ID ranges depending on firmware version) or ~ to increment, ~- to decrement, or r for random.

As per coding guidelines, use standard GFM pipe tables for Markdown documentation.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
pal | byte | ID of an available palette (see [Palettes](#palettes) section for available ID ranges depending on firmware version) or ~ to increment, ~- to decrement, or r for random.
| pal | byte | ID of an available palette (see [Palettes](`#palettes`) section for available ID ranges depending on firmware version) or ~ to increment, ~- to decrement, or r for random.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)

[warning] 199-199: Table pipe style
Expected: leading_only; Actual: no_leading_or_trailing; Missing leading pipe

(MD055, table-pipe-style)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/interfaces/json-api.md` at line 199, The table row for the "pal" field
is missing the leading pipe, which breaks GFM pipe table style and triggers
MD055; update the table row for the pal entry (the line containing "pal | byte |
ID of an available palette...") to include the leading "|" at the start of the
line so it conforms to standard Markdown pipe-table syntax and passes linting.

<a id="seg-sel"></a>sel | bool | `true` if the segment is selected. Selected segments will have their state (color/FX) updated by APIs that don't support segments (e.g. UDP sync, HTTP API). If no segment is selected, the first segment (_id_:`0`) will behave as if selected. WLED will report the state of the first (lowest _id_) segment that is selected to APIs (HTTP, MQTT, Blynk...), or `mainseg` in case no segment is selected and for the UDP API. Live data is always applied to all LEDs regardless of segment configuration.
rev | bool | Flips the segment (in horizontal dimension for 2D set-up), causing animations to change direction.
rY | bool | Flips the 2D segment in vertical dimension. _(available since 0.14.0)_
Expand Down Expand Up @@ -247,6 +247,9 @@ lip | string | Realtime data source IP address
ws | -1 to 8 | Number of currently connected WebSockets clients. -1 indicates that WS is unsupported in this build.
fxcount | byte | Number of effects included.
palcount | uint16 | Number of palettes configured.
cpalcount | byte | Number of custom user-created palettes. _(available since 0.11.0)_
umpalcount | byte | Number of usermod-registered palettes. _(available since 16.0.0)_
umpalnames | array of strings | Names of usermod-registered palettes. _(available since 16.0.0)_

@coderabbitai coderabbitai Bot May 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Normalize pipe-table formatting for the newly added rows.

The newly added table rows here also miss the leading |, causing the same MD055 warnings.

Suggested fix 
-cpalcount | byte | Number of custom user-created palettes. _(available since 0.11.0)_
-umpalcount | byte | Number of usermod-registered palettes. _(available since 16.0.0)_
-umpalnames | array of strings | Names of usermod-registered palettes. _(available since 16.0.0)_
+| cpalcount | byte | Number of custom user-created palettes. _(available since 0.11.0)_
+| umpalcount | byte | Number of usermod-registered palettes. _(available since 16.0.0)_
+| umpalnames | array of strings | Names of usermod-registered palettes. _(available since 16.0.0)_

-Set palette 0 on segment 0 | `{"seg":[{"id":0,"pal":0}]}`
-Set a custom palette (ID 200) on segment 1 | `{"seg":[{"id":1,"pal":200}]}`
+| Set palette 0 on segment 0 | `{"seg":[{"id":0,"pal":0}]}`
+| Set a custom palette (ID 200) on segment 1 | `{"seg":[{"id":1,"pal":200}]}`

As per coding guidelines, use standard GFM pipe tables for Markdown documentation.

Also applies to: 281-282

🧰 Tools
🪛 markdownlint-cli2 (0.22.1)

[warning] 250-250: Table pipe style
Expected: leading_only; Actual: no_leading_or_trailing; Missing leading pipe

(MD055, table-pipe-style)

[warning] 251-251: Table pipe style
Expected: leading_only; Actual: no_leading_or_trailing; Missing leading pipe

(MD055, table-pipe-style)

[warning] 252-252: Table pipe style
Expected: leading_only; Actual: no_leading_or_trailing; Missing leading pipe

(MD055, table-pipe-style)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/interfaces/json-api.md` around lines 250 - 252, The three newly added
table rows for cpalcount, umpalcount, and umpalnames are missing the leading
pipe character which breaks GFM pipe-table formatting and triggers MD055; update
the rows referenced by the symbols cpalcount, umpalcount, and umpalnames to
start with a leading '|' and match the surrounding pipe-table format (also apply
the same fix to the analogous rows at the other occurrence mentioned around
umpalcount/umpalnames at the later section).

_wifi_ | object | Info about current signal strength
wifi.bssid | string | The BSSID of the currently connected network.
wifi.signal | 0 to 100 | Relative signal quality of the current connection.
Expand Down Expand Up @@ -275,6 +278,8 @@ Examples of frequently requested custom API:
Cycle presets between 1 and 6 | `{"ps":"1~6~"}`
Select random effect on _all selected_ segments | `{"seg":{"fx":"r"}}`
Select random palette between 5 and 10 on segment 2 | `{"seg":[{"id":2,"pal":"5~10r"}]}`
Set palette 0 on segment 0 | `{"seg":[{"id":0,"pal":0}]}`
Set a custom palette (ID 200) on segment 1 | `{"seg":[{"id":1,"pal":200}]}`
Change segment 0 name | `{"seg":[{"id":0,"n":"Your custom ASCII text"}]}`
Freeze or unfreeze an effect | `{"seg":[{"id":0,"frz":true}]}` or `{"seg":[{"id":0,"frz":false}]}`
Night light | `{"nl":{"on":true,"dur":10,"mode":0}}`
Expand Down Expand Up @@ -316,6 +321,52 @@ Matrices are handled as a non-serpentine layout.
!!! info "Brightness interaction"
For your colors to apply correctly, make sure the desired brightness is set beforehand. Turning on the LEDs from an off state and setting individual LEDs in the same JSON request will _not_ work!

#### Palettes

The JSON API supports three types of palettes:

- **Built-in palettes**: Fixed palettes included in the WLED firmware
- **Custom palettes**: User-defined palettes created via the web UI or API
- **Usermod palettes**: Palettes registered by usermods (WLED 16.0.0+ only)

The palette ID scheme (used in the `pal` parameter) changed significantly in WLED 16.0.0.

##### Legacy (WLED < 16.0.0)

- **Built-in palettes**: IDs `0` to `info.palcount - 1`
- **Custom palettes**: IDs counting down from `255` (ID `255`, `254`, `253`, etc.)
- The number of custom palettes is reported via `info.cpalcount`

##### WLED 16.0.0 and later

Starting with WLED 16.0.0, the palette ID space was reorganized into fixed ranges:

- **Built-in palettes**: IDs `0` to `71` (72 fixed palettes)
- **Custom palettes**: IDs `72` to `200` (allocated from `200` downward)
- The number of custom palettes is reported via `info.cpalcount`
- First custom palette gets ID `200`, second gets ID `199`, etc.
- Up to 129 custom palette slots available (ESP32) or 10 (ESP8266)
- **Usermod palettes**: IDs `201` to `255` (allocated from `255` downward)
- Reserved for palettes registered by usermods
- First usermod palette gets ID `255`, second gets ID `254`, etc.
- Up to 55 usermod palette slots available

##### Palette naming
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Outdated

Palette names are obtained from different sources depending on the palette type:

**Built-in palettes:**
- Names are provided in the JSON API response under the `palettes` array (for `/json` or `/json/pal` endpoints)
- Each index in the array corresponds to palette ID of the same index

**Custom palettes:**
- Generated automatically as `"Custom 1"`, `"Custom 2"`, etc.
- Based on the count reported via `info.cpalcount`

**Usermod palettes (WLED 16.0.0+):**
- Names are provided in the `info.umpalnames` array
- Must have exactly `info.umpalcount` entries in `umpalnames` for all usermod palettes to be displayed

#### Playlists

(Available since 0.11.0)
Expand Down
Loading