> ## Documentation Index
> Fetch the complete documentation index at: https://rockboxzig.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP REST

> JSON over HTTP on port 6063. The endpoints used internally by the web UI and SDK clients.

The REST server runs on **port 6063** by default (override with
`ROCKBOX_TCP_PORT`). Every endpoint is JSON in / JSON out, except where
noted (some commands return plain-text status codes).

The full schema is published as
[OpenAPI 3.1](https://rockboxzig.mintlify.site/api-reference/openapi.json) and rendered as one page per
endpoint in the sidebar — explore by tag or jump to a specific operation.

## Quick smoke test

```sh theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
curl -s http://localhost:6063/version
curl -s http://localhost:6063/player/status
curl -s http://localhost:6063/playlists/amount
```

## Common operations

```sh Now playing theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
curl -s http://localhost:6063/player/current-track | jq .title,.artist
```

```sh Search theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
curl -s 'http://localhost:6063/search?q=daft+punk' | jq '.tracks[].title'
```

```sh Play an album theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
ALBUM_ID=$(curl -s http://localhost:6063/albums | jq -r '.[0].id')
TRACKS=$(curl -s "http://localhost:6063/albums/$ALBUM_ID/tracks" | jq '[.[].path]')
curl -X POST -H 'Content-Type: application/json' \
  -d "{\"name\":\"album\",\"tracks\":$TRACKS}" \
  http://localhost:6063/playlists
curl -X PUT 'http://localhost:6063/playlists/start?start_index=0'
```

```sh Volume up theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
curl -X PUT -H 'Content-Type: application/json' \
  -d '{"steps":3}' \
  http://localhost:6063/player/volume
```

```sh Switch to a discovered Chromecast theme={"theme":{"light":"catppuccin-latte","dark":"min-dark"}}
ID=$(curl -s http://localhost:6063/devices | jq -r '.[] | select(.is_cast_device) | .id' | head -1)
curl -X PUT "http://localhost:6063/devices/$ID/connect"
```

## Notable behaviours

* **Responses sometimes return plain text.** A few mutations return a
  status integer or insertion index in the body as text rather than JSON
  (`/playlists`, `/playlists/{id}/tracks`, `/scan-library`). The OpenAPI
  spec marks these explicitly.
* **Saved playlist mutations return `204`** with no body.
* **Bluetooth routes only exist on Linux.** They are conditionally
  registered at compile time.
* **The HTTP server runs on its own thread** so actix's worker pool is
  not pinned to the Rockbox cooperative scheduler. See
  [Architecture › Overview](https://rockboxzig.mintlify.site/architecture/overview.md) for the lifecycle.

## Server details

* Bind address — `0.0.0.0:$ROCKBOX_TCP_PORT` (default `6063`).
* CORS — permissive (`actix_cors::Cors::permissive()`) so browser-based
  clients can hit it without preflight pain.
* The OpenAPI document is also served live at
  `http://localhost:6063/openapi.json`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.