> ## 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.

# Write endpoints

> Playback control endpoints in the Velora local API that require write permission.

All endpoints on this page require a token with `write` permission.

<Info>
  Write endpoints are `POST` only.
</Info>

## `POST /play`

Starts playback. You can provide a `track_id` to play a specific track.

Request body:

```json theme={null}
{
  "track_id": "track_123"
}
```

`track_id` is optional. Without it, Velora can treat the request as a resume depending on current player state.

Success response:

```json theme={null}
{
  "ok": true,
  "track_id": "track_123"
}
```

## `POST /pause`

Pauses playback.

```json theme={null}
{
  "ok": true
}
```

## `POST /next`

Skips to the next track.

```json theme={null}
{
  "ok": true
}
```

## `POST /previous`

Skips to the previous track.

```json theme={null}
{
  "ok": true
}
```

## `POST /seek`

Seeks playback to a position in milliseconds.

Request body:

```json theme={null}
{
  "position": 60000
}
```

Rules:

* `position` must be a number
* `position` must be greater than or equal to `0`

Invalid position response (`400`):

```json theme={null}
{
  "error": "position must be a non-negative number (milliseconds)"
}
```

Success response:

```json theme={null}
{
  "ok": true,
  "position": 60000
}
```

## `POST /toggle` and `POST /toggle-play`

Both paths toggle play and pause.

Success response:

```json theme={null}
{
  "ok": true,
  "is_playing": false
}
```

## cURL examples

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

```bash theme={null}
curl -X POST http://127.0.0.1:39031/seek \
  -H "Authorization: Bearer velora_your_token" \
  -H "Content-Type: application/json" \
  -d '{"position": 90000}'
```