Playlist

GET /playlists

Get all playlists

Returns all playlists in the world with their tracks/sounds, including playing status, mode, and volume information.

Required scope: playlist:control

Parameters

Name	Type	Required	Source	Description
clientId	string		query	Client ID for the Foundry world
userId	string		query, body	Foundry user ID or username to scope permissions (omit for GM-level access)

Returns

array - Array of playlists with their sounds

Try It Out

Code Examples

JavaScript

const baseUrl = 'http://localhost:3010';
const path = '/playlists';
const params = {
  clientId: 'fvtt_099ad17ea199e7e3'
};
const queryString = new URLSearchParams(params).toString();
const url = `${baseUrl}${path}?${queryString}`;

const response = await fetch(url, {
  method: 'GET',
  headers: {
    'x-api-key': 'your-api-key-here'
  }
});
const data = await response.json();
console.log(data);

cURL

curl -X GET 'http://localhost:3010/playlists?clientId=fvtt_099ad17ea199e7e3' \
  -H "x-api-key: your-api-key-here"

Python

import requests

base_url = 'http://localhost:3010'
path = '/playlists'
params = {
    'clientId': 'fvtt_099ad17ea199e7e3'
}
url = f'{base_url}{path}'

response = requests.get(
    url,
    params=params,
    headers={
        'x-api-key': 'your-api-key-here'
    }
)
data = response.json()
print(data)

TypeScript

import axios from 'axios';

(async () => {
  const baseUrl = 'http://localhost:3010';
  const path = '/playlists';
  const params = {
    clientId: 'fvtt_099ad17ea199e7e3'
  };
  const queryString = new URLSearchParams(params).toString();
  const url = `${baseUrl}${path}?${queryString}`;

  const response = await axios({
    method: 'get',
    headers: {
      'x-api-key': 'your-api-key-here'
    },
    url
  });
  const data = response.data;
  console.log(data);
})();

Emojicode

📦 sockets 🏠

💭 Emojicode HTTP Client
💭 Compile: emojicodec example.🍇 -o example
💭 Run: ./example

🏁 🍇
  💭 Connection settings
  🔤localhost🔤 ➡️ host
  3010 ➡️ port
  🔤/playlists🔤 ➡️ path

  💭 Query parameters
  🔤clientId=fvtt_099ad17ea199e7e3🔤 ➡️ clientId
  🔤?🧲clientId🧲🔤 ➡️ queryString

  💭 Build HTTP request
  🔤GET /playlists🧲queryString🧲 HTTP/1.1❌r❌nHost: localhost:3010❌r❌nx-api-key: your-api-key-here❌r❌n❌r❌n🔤 ➡️ request

  💭 Connect and send
  🍺 🆕📞 host port❗ ➡️ socket
  🍺 💬 socket 📇 request❗❗
  
  💭 Read and print response
  🍺 👂 socket 4096❗ ➡️ data
  😀 🍺 🔡 data❗❗
  
  💭 Close socket
  🚪 socket❗
🍉

Response

Status: 200

{
  "type": "get-playlists-result",
  "requestId": "get-playlists_1778896440084",
  "data": {
    "playlists": [
      0: { 8 keys }
    ]
  }
}

---

POST /playlist/play

Play a playlist or specific sound

Starts playback of an entire playlist or a specific sound within it. The playlist can be identified by ID or name. Optionally specify a specific sound/track to play within the playlist.

Required scope: playlist:control

Parameters

Name	Type	Required	Source	Description
clientId	string		query	Client ID for the Foundry world
playlistId	string		body, query	ID of the playlist (optional if playlistName provided)
playlistName	string		body, query	Name of the playlist (optional if playlistId provided)
soundId	string		body, query	ID of a specific sound to play within the playlist
soundName	string		body, query	Name of a specific sound to play (optional if soundId provided)
userId	string		query, body	Foundry user ID or username to scope permissions (omit for GM-level access)

Returns

object - Playback status confirmation

Try It Out

Code Examples

JavaScript

const baseUrl = 'http://localhost:3010';
const path = '/playlist/play';
const params = {
  clientId: 'fvtt_099ad17ea199e7e3'
};
const queryString = new URLSearchParams(params).toString();
const url = `${baseUrl}${path}?${queryString}`;

const response = await fetch(url, {
  method: 'POST',
  headers: {
    'x-api-key': 'your-api-key-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "playlistName": "test-rest-api-playlist"
    })
});
const data = await response.json();
console.log(data);

cURL

curl -X POST 'http://localhost:3010/playlist/play?clientId=fvtt_099ad17ea199e7e3' \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"playlistName":"test-rest-api-playlist"}'

Python

import requests

base_url = 'http://localhost:3010'
path = '/playlist/play'
params = {
    'clientId': 'fvtt_099ad17ea199e7e3'
}
url = f'{base_url}{path}'

response = requests.post(
    url,
    params=params,
    headers={
        'x-api-key': 'your-api-key-here',
        'Content-Type': 'application/json'
    },
    json={
      "playlistName": "test-rest-api-playlist"
    }
)
data = response.json()
print(data)

TypeScript

import axios from 'axios';

(async () => {
  const baseUrl = 'http://localhost:3010';
  const path = '/playlist/play';
  const params = {
    clientId: 'fvtt_099ad17ea199e7e3'
  };
  const queryString = new URLSearchParams(params).toString();
  const url = `${baseUrl}${path}?${queryString}`;

  const response = await axios({
    method: 'post',
    headers: {
      'x-api-key': 'your-api-key-here',
      'Content-Type': 'application/json'
    },
    url,
    data: {
        "playlistName": "test-rest-api-playlist"
      }
  });
  const data = response.data;
  console.log(data);
})();

Emojicode

📦 sockets 🏠

💭 Emojicode HTTP Client
💭 Compile: emojicodec example.🍇 -o example
💭 Run: ./example

🏁 🍇
  💭 Connection settings
  🔤localhost🔤 ➡️ host
  3010 ➡️ port
  🔤/playlist/play🔤 ➡️ path

  💭 Query parameters
  🔤clientId=fvtt_099ad17ea199e7e3🔤 ➡️ clientId
  🔤?🧲clientId🧲🔤 ➡️ queryString

  💭 Request body
  🔤{"playlistName":"test-rest-api-playlist"}🔤 ➡️ body

  💭 Build HTTP request
  🔤POST /playlist/play🧲queryString🧲 HTTP/1.1❌r❌nHost: localhost:3010❌r❌nx-api-key: your-api-key-here❌r❌nContent-Type: application/json❌r❌nContent-Length: 41❌r❌n❌r❌n🧲body🧲🔤 ➡️ request

  💭 Connect and send
  🍺 🆕📞 host port❗ ➡️ socket
  🍺 💬 socket 📇 request❗❗
  
  💭 Read and print response
  🍺 👂 socket 4096❗ ➡️ data
  😀 🍺 🔡 data❗❗
  
  💭 Close socket
  🚪 socket❗
🍉

Response

Status: 200

{
  "type": "playlist-play-result",
  "requestId": "playlist-play_1778896440090",
  "data": {
    "playlist": {
      "id": "4lS0v0rGoaO5NnLq",
      "name": "test-rest-api-playlist",
      "description": "",
      "playing": true,
      "mode": 0,
      "folder": null,
      "sorting": "a",
      "sounds": [ 1 item ]
    }
  }
}

---

POST /playlist/stop

Stop a playlist

Stops playback of the specified playlist.

Required scope: playlist:control

Parameters

Name	Type	Required	Source	Description
clientId	string		query	Client ID for the Foundry world
playlistId	string		body, query	ID of the playlist (optional if playlistName provided)
playlistName	string		body, query	Name of the playlist (optional if playlistId provided)
userId	string		query, body	Foundry user ID or username to scope permissions (omit for GM-level access)

Returns

object - Stop confirmation

Try It Out

Code Examples

JavaScript

const baseUrl = 'http://localhost:3010';
const path = '/playlist/stop';
const params = {
  clientId: 'fvtt_099ad17ea199e7e3'
};
const queryString = new URLSearchParams(params).toString();
const url = `${baseUrl}${path}?${queryString}`;

const response = await fetch(url, {
  method: 'POST',
  headers: {
    'x-api-key': 'your-api-key-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "playlistName": "test-rest-api-playlist"
    })
});
const data = await response.json();
console.log(data);

cURL

curl -X POST 'http://localhost:3010/playlist/stop?clientId=fvtt_099ad17ea199e7e3' \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"playlistName":"test-rest-api-playlist"}'

Python

import requests

base_url = 'http://localhost:3010'
path = '/playlist/stop'
params = {
    'clientId': 'fvtt_099ad17ea199e7e3'
}
url = f'{base_url}{path}'

response = requests.post(
    url,
    params=params,
    headers={
        'x-api-key': 'your-api-key-here',
        'Content-Type': 'application/json'
    },
    json={
      "playlistName": "test-rest-api-playlist"
    }
)
data = response.json()
print(data)

TypeScript

import axios from 'axios';

(async () => {
  const baseUrl = 'http://localhost:3010';
  const path = '/playlist/stop';
  const params = {
    clientId: 'fvtt_099ad17ea199e7e3'
  };
  const queryString = new URLSearchParams(params).toString();
  const url = `${baseUrl}${path}?${queryString}`;

  const response = await axios({
    method: 'post',
    headers: {
      'x-api-key': 'your-api-key-here',
      'Content-Type': 'application/json'
    },
    url,
    data: {
        "playlistName": "test-rest-api-playlist"
      }
  });
  const data = response.data;
  console.log(data);
})();

Emojicode

📦 sockets 🏠

💭 Emojicode HTTP Client
💭 Compile: emojicodec example.🍇 -o example
💭 Run: ./example

🏁 🍇
  💭 Connection settings
  🔤localhost🔤 ➡️ host
  3010 ➡️ port
  🔤/playlist/stop🔤 ➡️ path

  💭 Query parameters
  🔤clientId=fvtt_099ad17ea199e7e3🔤 ➡️ clientId
  🔤?🧲clientId🧲🔤 ➡️ queryString

  💭 Request body
  🔤{"playlistName":"test-rest-api-playlist"}🔤 ➡️ body

  💭 Build HTTP request
  🔤POST /playlist/stop🧲queryString🧲 HTTP/1.1❌r❌nHost: localhost:3010❌r❌nx-api-key: your-api-key-here❌r❌nContent-Type: application/json❌r❌nContent-Length: 41❌r❌n❌r❌n🧲body🧲🔤 ➡️ request

  💭 Connect and send
  🍺 🆕📞 host port❗ ➡️ socket
  🍺 💬 socket 📇 request❗❗
  
  💭 Read and print response
  🍺 👂 socket 4096❗ ➡️ data
  😀 🍺 🔡 data❗❗
  
  💭 Close socket
  🚪 socket❗
🍉

Response

Status: 200

{
  "type": "playlist-stop-result",
  "requestId": "playlist-stop_1778896440103",
  "data": {
    "playlist": {
      "id": "4lS0v0rGoaO5NnLq",
      "name": "test-rest-api-playlist",
      "description": "",
      "playing": false,
      "mode": 0,
      "folder": null,
      "sorting": "a",
      "sounds": [ 1 item ]
    }
  }
}

---

POST /playlist/next

Skip to next track in a playlist

Advances to the next sound/track in the specified playlist.

Required scope: playlist:control

Parameters

Name	Type	Required	Source	Description
clientId	string		query	Client ID for the Foundry world
playlistId	string		body, query	ID of the playlist (optional if playlistName provided)
playlistName	string		body, query	Name of the playlist (optional if playlistId provided)
userId	string		query, body	Foundry user ID or username to scope permissions (omit for GM-level access)

Returns

object - Next track information

Try It Out

Code Examples

JavaScript

const baseUrl = 'http://localhost:3010';
const path = '/playlist/next';
const params = {
  clientId: 'fvtt_099ad17ea199e7e3'
};
const queryString = new URLSearchParams(params).toString();
const url = `${baseUrl}${path}?${queryString}`;

const response = await fetch(url, {
  method: 'POST',
  headers: {
    'x-api-key': 'your-api-key-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "playlistName": "test-rest-api-playlist"
    })
});
const data = await response.json();
console.log(data);

cURL

curl -X POST 'http://localhost:3010/playlist/next?clientId=fvtt_099ad17ea199e7e3' \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"playlistName":"test-rest-api-playlist"}'

Python

import requests

base_url = 'http://localhost:3010'
path = '/playlist/next'
params = {
    'clientId': 'fvtt_099ad17ea199e7e3'
}
url = f'{base_url}{path}'

response = requests.post(
    url,
    params=params,
    headers={
        'x-api-key': 'your-api-key-here',
        'Content-Type': 'application/json'
    },
    json={
      "playlistName": "test-rest-api-playlist"
    }
)
data = response.json()
print(data)

TypeScript

import axios from 'axios';

(async () => {
  const baseUrl = 'http://localhost:3010';
  const path = '/playlist/next';
  const params = {
    clientId: 'fvtt_099ad17ea199e7e3'
  };
  const queryString = new URLSearchParams(params).toString();
  const url = `${baseUrl}${path}?${queryString}`;

  const response = await axios({
    method: 'post',
    headers: {
      'x-api-key': 'your-api-key-here',
      'Content-Type': 'application/json'
    },
    url,
    data: {
        "playlistName": "test-rest-api-playlist"
      }
  });
  const data = response.data;
  console.log(data);
})();

Emojicode

📦 sockets 🏠

💭 Emojicode HTTP Client
💭 Compile: emojicodec example.🍇 -o example
💭 Run: ./example

🏁 🍇
  💭 Connection settings
  🔤localhost🔤 ➡️ host
  3010 ➡️ port
  🔤/playlist/next🔤 ➡️ path

  💭 Query parameters
  🔤clientId=fvtt_099ad17ea199e7e3🔤 ➡️ clientId
  🔤?🧲clientId🧲🔤 ➡️ queryString

  💭 Request body
  🔤{"playlistName":"test-rest-api-playlist"}🔤 ➡️ body

  💭 Build HTTP request
  🔤POST /playlist/next🧲queryString🧲 HTTP/1.1❌r❌nHost: localhost:3010❌r❌nx-api-key: your-api-key-here❌r❌nContent-Type: application/json❌r❌nContent-Length: 41❌r❌n❌r❌n🧲body🧲🔤 ➡️ request

  💭 Connect and send
  🍺 🆕📞 host port❗ ➡️ socket
  🍺 💬 socket 📇 request❗❗
  
  💭 Read and print response
  🍺 👂 socket 4096❗ ➡️ data
  😀 🍺 🔡 data❗❗
  
  💭 Close socket
  🚪 socket❗
🍉

Response

Status: 200

{
  "type": "playlist-next-result",
  "requestId": "playlist-next_1778896440096",
  "data": {
    "playlist": {
      "id": "4lS0v0rGoaO5NnLq",
      "name": "test-rest-api-playlist",
      "description": "",
      "playing": true,
      "mode": 0,
      "folder": null,
      "sorting": "a",
      "sounds": [ 1 item ]
    }
  }
}

---

POST /playlist/volume

Set volume for a playlist or specific sound

Adjusts the volume of an entire playlist or a specific sound within it. Volume is specified as a float between 0 (silent) and 1 (full volume).

Required scope: playlist:control

Parameters

Name	Type	Required	Source	Description
volume	number	✓	body, query	Volume level from 0.0 (silent) to 1.0 (full volume)
clientId	string		query	Client ID for the Foundry world
playlistId	string		body, query	ID of the playlist (optional if playlistName provided)
playlistName	string		body, query	Name of the playlist (optional if playlistId provided)
soundId	string		body, query	ID of a specific sound to adjust volume for
soundName	string		body, query	Name of a specific sound to adjust volume for (optional if soundId provided)
userId	string		query, body	Foundry user ID or username to scope permissions (omit for GM-level access)

Returns

object - Updated volume level

Try It Out

Code Examples

JavaScript

const baseUrl = 'http://localhost:3010';
const path = '/playlist/volume';
const params = {
  clientId: 'fvtt_099ad17ea199e7e3'
};
const queryString = new URLSearchParams(params).toString();
const url = `${baseUrl}${path}?${queryString}`;

const response = await fetch(url, {
  method: 'POST',
  headers: {
    'x-api-key': 'your-api-key-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "playlistName": "test-rest-api-playlist",
      "volume": 0.75
    })
});
const data = await response.json();
console.log(data);

cURL

curl -X POST 'http://localhost:3010/playlist/volume?clientId=fvtt_099ad17ea199e7e3' \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"playlistName":"test-rest-api-playlist","volume":0.75}'

Python

import requests

base_url = 'http://localhost:3010'
path = '/playlist/volume'
params = {
    'clientId': 'fvtt_099ad17ea199e7e3'
}
url = f'{base_url}{path}'

response = requests.post(
    url,
    params=params,
    headers={
        'x-api-key': 'your-api-key-here',
        'Content-Type': 'application/json'
    },
    json={
      "playlistName": "test-rest-api-playlist",
      "volume": 0.75
    }
)
data = response.json()
print(data)

TypeScript

import axios from 'axios';

(async () => {
  const baseUrl = 'http://localhost:3010';
  const path = '/playlist/volume';
  const params = {
    clientId: 'fvtt_099ad17ea199e7e3'
  };
  const queryString = new URLSearchParams(params).toString();
  const url = `${baseUrl}${path}?${queryString}`;

  const response = await axios({
    method: 'post',
    headers: {
      'x-api-key': 'your-api-key-here',
      'Content-Type': 'application/json'
    },
    url,
    data: {
        "playlistName": "test-rest-api-playlist",
        "volume": 0.75
      }
  });
  const data = response.data;
  console.log(data);
})();

Emojicode

📦 sockets 🏠

💭 Emojicode HTTP Client
💭 Compile: emojicodec example.🍇 -o example
💭 Run: ./example

🏁 🍇
  💭 Connection settings
  🔤localhost🔤 ➡️ host
  3010 ➡️ port
  🔤/playlist/volume🔤 ➡️ path

  💭 Query parameters
  🔤clientId=fvtt_099ad17ea199e7e3🔤 ➡️ clientId
  🔤?🧲clientId🧲🔤 ➡️ queryString

  💭 Request body
  🔤{"playlistName":"test-rest-api-playlist","volume":0.75}🔤 ➡️ body

  💭 Build HTTP request
  🔤POST /playlist/volume🧲queryString🧲 HTTP/1.1❌r❌nHost: localhost:3010❌r❌nx-api-key: your-api-key-here❌r❌nContent-Type: application/json❌r❌nContent-Length: 55❌r❌n❌r❌n🧲body🧲🔤 ➡️ request

  💭 Connect and send
  🍺 🆕📞 host port❗ ➡️ socket
  🍺 💬 socket 📇 request❗❗
  
  💭 Read and print response
  🍺 👂 socket 4096❗ ➡️ data
  😀 🍺 🔡 data❗❗
  
  💭 Close socket
  🚪 socket❗
🍉

Response

Status: 200

{
  "type": "playlist-volume-result",
  "requestId": "playlist-volume_1778896440100",
  "data": {
    "playlist": {
      "id": "4lS0v0rGoaO5NnLq",
      "name": "test-rest-api-playlist",
      "description": "",
      "playing": true,
      "mode": 0,
      "folder": null,
      "sorting": "a",
      "sounds": [ 1 item ]
    }
  }
}

---

POST /stop-sound

Play a one-shot sound effect

Triggers playback of an audio file by its path. Useful for sound effects, ambient sounds, or any audio that should play once without being part of a playlist. Stop a playing sound Stops playback of a currently playing sound by its source path. If no src is provided, stops all currently playing sounds.

Required scope: playlist:control

Parameters

Name	Type	Required	Source	Description
clientId	string		query	Client ID for the Foundry world
src	string		body, query	Path to the audio file to stop (omit to stop all sounds)
userId	string		query, body	Foundry user ID or username to scope permissions (omit for GM-level access)

Returns

object - Stop confirmation

Try It Out

Code Examples

JavaScript

const baseUrl = 'http://localhost:3010';
const path = '/stop-sound';
const params = {
  clientId: 'fvtt_099ad17ea199e7e3'
};
const queryString = new URLSearchParams(params).toString();
const url = `${baseUrl}${path}?${queryString}`;

const response = await fetch(url, {
  method: 'POST',
  headers: {
    'x-api-key': 'your-api-key-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "src": "sounds/dice.wav"
    })
});
const data = await response.json();
console.log(data);

cURL

curl -X POST 'http://localhost:3010/stop-sound?clientId=fvtt_099ad17ea199e7e3' \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"src":"sounds/dice.wav"}'

Python

import requests

base_url = 'http://localhost:3010'
path = '/stop-sound'
params = {
    'clientId': 'fvtt_099ad17ea199e7e3'
}
url = f'{base_url}{path}'

response = requests.post(
    url,
    params=params,
    headers={
        'x-api-key': 'your-api-key-here',
        'Content-Type': 'application/json'
    },
    json={
      "src": "sounds/dice.wav"
    }
)
data = response.json()
print(data)

TypeScript

import axios from 'axios';

(async () => {
  const baseUrl = 'http://localhost:3010';
  const path = '/stop-sound';
  const params = {
    clientId: 'fvtt_099ad17ea199e7e3'
  };
  const queryString = new URLSearchParams(params).toString();
  const url = `${baseUrl}${path}?${queryString}`;

  const response = await axios({
    method: 'post',
    headers: {
      'x-api-key': 'your-api-key-here',
      'Content-Type': 'application/json'
    },
    url,
    data: {
        "src": "sounds/dice.wav"
      }
  });
  const data = response.data;
  console.log(data);
})();

Emojicode

📦 sockets 🏠

💭 Emojicode HTTP Client
💭 Compile: emojicodec example.🍇 -o example
💭 Run: ./example

🏁 🍇
  💭 Connection settings
  🔤localhost🔤 ➡️ host
  3010 ➡️ port
  🔤/stop-sound🔤 ➡️ path

  💭 Query parameters
  🔤clientId=fvtt_099ad17ea199e7e3🔤 ➡️ clientId
  🔤?🧲clientId🧲🔤 ➡️ queryString

  💭 Request body
  🔤{"src":"sounds/dice.wav"}🔤 ➡️ body

  💭 Build HTTP request
  🔤POST /stop-sound🧲queryString🧲 HTTP/1.1❌r❌nHost: localhost:3010❌r❌nx-api-key: your-api-key-here❌r❌nContent-Type: application/json❌r❌nContent-Length: 25❌r❌n❌r❌n🧲body🧲🔤 ➡️ request

  💭 Connect and send
  🍺 🆕📞 host port❗ ➡️ socket
  🍺 💬 socket 📇 request❗❗
  
  💭 Read and print response
  🍺 👂 socket 4096❗ ➡️ data
  😀 🍺 🔡 data❗❗
  
  💭 Close socket
  🚪 socket❗
🍉

Response

Status: 200

{
  "type": "stop-sound-result",
  "requestId": "stop-sound_1778896440110",
  "data": {
    "stopped": 0,
    "src": "sounds/dice.wav"
  }
}