> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velora.crickdevs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Read endpoints

> Auth requirements and response shapes for Velora local API read operations.

Use a token with `read` permission.

## Authentication examples

Header-based auth:

```bash theme={null}
curl http://127.0.0.1:39031/current-track \
  -H "Authorization: Bearer velora_your_token"
```

Query-based auth:

```bash theme={null}
curl "http://127.0.0.1:39031/current-track?access_token=velora_your_token"
```

## `GET /health`

Returns server health and bind details. No token required.

```json theme={null}
{
  "ok": true,
  "status": "running",
  "port": 39031,
  "host": "127.0.0.1"
}
```

## `GET /current-track`

Returns the current playback track snapshot.

```json theme={null}
{
  "track": {
    "id": "track_123",
    "title": "Song Name",
    "artist": "Artist Name",
    "album": "Album Name",
    "cover_url": "https://...",
    "thumbnail_url": "https://...",
    "duration": 200000,
    "position": 54321,
    "is_playing": true
  }
}
```

## `GET /playback-state`

Returns playback flags.

```json theme={null}
{
  "is_playing": true,
  "shuffle": false,
  "repeat": "off"
}
```

`repeat` values are normalized to `off`, `one`, `all`, or `on`.

## `GET /playback-queue`

Returns queue and playhead metadata.

```json theme={null}
{
  "queue": [
    {
      "id": "track_123",
      "title": "Song Name",
      "artist": "Artist Name",
      "duration": 200,
      "cover_url": "https://...",
      "thumbnail_url": "https://..."
    }
  ],
  "current_index": 0,
  "current_track_id": "track_123",
  "current_track_cover_url": "https://...",
  "is_playing": true,
  "shuffle": false,
  "repeat": "off",
  "updated_at": "2026-01-01T00:00:00.000Z"
}
```

## `GET /user/public`

Returns a normalized public profile snapshot of the active user.

```json theme={null}
{
  "user": {
    "id": "usr_1",
    "username": "velorauser",
    "name": "Velora User",
    "profile_image_url": "https://..."
  },
  "updated_at": "2026-01-01T00:00:00.000Z"
}
```