Scene

GET /scene

Get scene(s)

Retrieves one or more scenes by ID, name, active status, viewed status, or all.

Required scope: scene:read

Parameters

Name	Type	Source	Description
clientId	string	query	Client ID for the Foundry world
sceneId	string	query	ID of a specific scene to retrieve
name	string	query	Name of the scene to retrieve
active	boolean	query	Set to true to get the currently active scene
viewed	boolean	query	Set to true to get the currently viewed scene
all	boolean	query	Set to true to get all scenes
userId	string	query, body	Foundry user ID or username to scope permissions (omit for GM-level access)

Returns

object - Scene data

Try It Out

Code Examples

JavaScript
cURL
Python
TypeScript
Emojicode

const baseUrl = 'http://localhost:3010';
const path = '/scene';
const params = {
  clientId: 'fvtt_099ad17ea199e7e3',
  all: 'true'
};
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 -X GET 'http://localhost:3010/scene?clientId=fvtt_099ad17ea199e7e3&all=true' \
  -H "x-api-key: your-api-key-here"

import requests

base_url = 'http://localhost:3010'
path = '/scene'
params = {
    'clientId': 'fvtt_099ad17ea199e7e3',
    'all': 'true'
}
url = f'{base_url}{path}'

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

import axios from 'axios';

(async () => {
  const baseUrl = 'http://localhost:3010';
  const path = '/scene';
  const params = {
    clientId: 'fvtt_099ad17ea199e7e3',
    all: 'true'
  };
  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);
})();

📦 sockets 🏠

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

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

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

  💭 Build HTTP request
  🔤GET /scene🧲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-scene-result",
  "requestId": "get-scene_1778896417813",
  "data": [
    0: {
      "name": "Scene",
      "_id": "i01IgzYFzGddbTtP",
      "active": false,
      "navigation": true,
      "navOrder": 0,
      "background": { 11 keys },
      "foreground": null,
      "foregroundElevation": null,
      "thumb": null,
      "width": 4000,
      "height": 3000,
      "padding": 0.25,
      "initial": { 3 keys },
      "backgroundColor": "#999999",
      "grid": { 8 keys },
      "tokenVision": true,
      "fog": { 3 keys },
      "environment": { 6 keys },
      "drawings": [],
      "tokens": [],
      "lights": [],
      "notes": [],
      "sounds": [],
      "regions": [],
      "templates": [],
      "tiles": [],
      "walls": [],
      "playlist": null,
      "playlistSound": null,
      "journal": null,
      "journalEntryPage": null,
      "weather": "",
      "folder": null,
      "sort": 0,
      "ownership": { 2 keys },
      "flags": {},
      "_stats": { 9 keys }
    },
    1: {
      "name": "test",
      "_id": "2xFy4d19bDsP08Aw",
      "active": false,
      "navigation": true,
      "navOrder": 0,
      "background": { 11 keys },
      "foreground": null,
      "foregroundElevation": null,
      "thumb": null,
      "width": 4000,
      "height": 3000,
      "padding": 0.25,
      "initial": { 3 keys },
      "backgroundColor": "#999999",
      "grid": { 8 keys },
      "tokenVision": true,
      "fog": { 3 keys },
      "environment": { 6 keys },
      "drawings": [],
      "tokens": [],
      "lights": [],
      "notes": [],
      "sounds": [],
      "regions": [],
      "templates": [],
      "tiles": [],
      "walls": [],
      "playlist": null,
      "playlistSound": null,
      "journal": null,
      "journalEntryPage": null,
      "weather": "",
      "folder": null,
      "sort": 0,
      "ownership": { 2 keys },
      "flags": {},
      "_stats": { 9 keys }
    },
    2: {
      "name": "test",
      "_id": "9AxQS1AJfhieexNT",
      "active": false,
      "navigation": true,
      "navOrder": 0,
      "background": { 11 keys },
      "foreground": null,
      "foregroundElevation": null,
      "thumb": null,
      "width": 4000,
      "height": 3000,
      "padding": 0.25,
      "initial": { 3 keys },
      "backgroundColor": "#999999",
      "grid": { 8 keys },
      "tokenVision": true,
      "fog": { 3 keys },
      "environment": { 6 keys },
      "drawings": [],
      "tokens": [],
      "lights": [],
      "notes": [],
      "sounds": [],
      "regions": [],
      "templates": [],
      "tiles": [],
      "walls": [],
      "playlist": null,
      "playlistSound": null,
      "journal": null,
      "journalEntryPage": null,
      "weather": "",
      "folder": null,
      "sort": 0,
      "ownership": { 2 keys },
      "flags": {},
      "_stats": { 9 keys }
    },
    3: {
      "name": "test",
      "_id": "E216rK2779fPDqiH",
      "active": false,
      "navigation": true,
      "navOrder": 0,
      "background": { 11 keys },
      "foreground": null,
      "foregroundElevation": null,
      "thumb": null,
      "width": 4000,
      "height": 3000,
      "padding": 0.25,
      "initial": { 3 keys },
      "backgroundColor": "#999999",
      "grid": { 8 keys },
      "tokenVision": true,
      "fog": { 3 keys },
      "environment": { 6 keys },
      "drawings": [],
      "tokens": [],
      "lights": [],
      "notes": [],
      "sounds": [],
      "regions": [],
      "templates": [],
      "tiles": [],
      "walls": [],
      "playlist": null,
      "playlistSound": null,
      "journal": null,
      "journalEntryPage": null,
      "weather": "",
      "folder": null,
      "sort": 0,
      "ownership": { 2 keys },
      "flags": {},
      "_stats": { 9 keys }
    },
    4: {
      "name": "test",
      "_id": "FIqMGxtWklfvb80c",
      "active": false,
      "navigation": true,
      "navOrder": 0,
      "background": { 11 keys },
      "foreground": null,
      "foregroundElevation": null,
      "thumb": null,
      "width": 4000,
      "height": 3000,
      "padding": 0.25,
      "initial": { 3 keys },
      "backgroundColor": "#999999",
      "grid": { 8 keys },
      "tokenVision": true,
      "fog": { 3 keys },
      "environment": { 6 keys },
      "drawings": [],
      "tokens": [],
      "lights": [],
      "notes": [],
      "sounds": [],
      "regions": [],
      "templates": [],
      "tiles": [],
      "walls": [],
      "playlist": null,
      "playlistSound": null,
      "journal": null,
      "journalEntryPage": null,
      "weather": "",
      "folder": null,
      "sort": 0,
      "ownership": { 2 keys },
      "flags": {},
      "_stats": { 9 keys }
    },
    5: {
      "name": "test",
      "_id": "HJ3cGhzRV8h0KqHp",
      "active": false,
      "navigation": true,
      "navOrder": 0,
      "background": { 11 keys },
      "foreground": null,
      "foregroundElevation": null,
      "thumb": null,
      "width": 4000,
      "height": 3000,
      "padding": 0.25,
      "initial": { 3 keys },
      "backgroundColor": "#999999",
      "grid": { 8 keys },
      "tokenVision": true,
      "fog": { 3 keys },
      "environment": { 6 keys },
      "drawings": [],
      "tokens": [],
      "lights": [],
      "notes": [],
      "sounds": [],
      "regions": [],
      "templates": [],
      "tiles": [],
      "walls": [],
      "playlist": null,
      "playlistSound": null,
      "journal": null,
      "journalEntryPage": null,
      "weather": "",
      "folder": null,
      "sort": 0,
      "ownership": { 2 keys },
      "flags": {},
      "_stats": { 9 keys }
    },
    6: {
      "_id": "OoTPjYkL2GjuQ2a7",
      "_stats": { 9 keys },
      "active": false,
      "background": { 11 keys },
      "backgroundColor": "#999999",
      "drawings": [ 2 items ],
      "environment": { 6 keys },
      "flags": {},
      "fog": { 3 keys },
      "foreground": null,
      "foregroundElevation": null,
      "grid": { 8 keys },
      "height": 2962,
      "initial": { 3 keys },
      "journal": null,
      "journalEntryPage": null,
      "lights": [ 1 item ],
      "name": "test",
      "navName": "",
      "navOrder": 0,
      "navigation": false,
      "notes": [ 1 item ],
      "ownership": { 3 keys },
      "padding": 0.25,
      "playlist": null,
      "playlistSound": null,
      "regions": [ 1 item ],
      "sort": 0,
      "sounds": [ 1 item ],
      "templates": [ 1 item ],
      "thumb": "worlds/5e-tables/assets/scenes/OoTPjYkL2GjuQ2a7-thumb.webp",
      "tiles": [ 1 item ],
      "tokenVision": true,
      "tokens": [ 1 item ],
      "walls": [ 6 items ],
      "weather": "",
      "width": 2221,
      "folder": null
    },
    7: {
      "name": "test",
      "_id": "X914jr7smFaAxr72",
      "active": false,
      "navigation": true,
      "navOrder": 0,
      "background": { 11 keys },
      "foreground": null,
      "foregroundElevation": null,
      "thumb": null,
      "width": 4000,
      "height": 3000,
      "padding": 0.25,
      "initial": { 3 keys },
      "backgroundColor": "#999999",
      "grid": { 8 keys },
      "tokenVision": true,
      "fog": { 3 keys },
      "environment": { 6 keys },
      "drawings": [],
      "tokens": [],
      "lights": [],
      "notes": [],
      "sounds": [],
      "regions": [],
      "templates": [],
      "tiles": [],
      "walls": [],
      "playlist": null,
      "playlistSound": null,
      "journal": null,
      "journalEntryPage": null,
      "weather": "",
      "folder": null,
      "sort": 0,
      "ownership": { 2 keys },
      "flags": {},
      "_stats": { 9 keys }
    },
    8: {
      "name": "test",
      "_id": "azpFAQYHh0s3yHML",
      "active": false,
      "navigation": true,
      "navOrder": 0,
      "background": { 11 keys },
      "foreground": null,
      "foregroundElevation": null,
      "thumb": null,
      "width": 4000,
      "height": 3000,
      "padding": 0.25,
      "initial": { 3 keys },
      "backgroundColor": "#999999",
      "grid": { 8 keys },
      "tokenVision": true,
      "fog": { 3 keys },
      "environment": { 6 keys },
      "drawings": [],
      "tokens": [],
      "lights": [],
      "notes": [],
      "sounds": [],
      "regions": [],
      "templates": [],
      "tiles": [],
      "walls": [],
      "playlist": null,
      "playlistSound": null,
      "journal": null,
      "journalEntryPage": null,
      "weather": "",
      "folder": null,
      "sort": 0,
      "ownership": { 2 keys },
      "flags": {},
      "_stats": { 9 keys }
    },
    9: {
      "name": "test",
      "_id": "nsoLECqbXXs1PrBZ",
      "active": false,
      "navigation": true,
      "navOrder": 0,
      "background": { 11 keys },
      "foreground": null,
      "foregroundElevation": null,
      "thumb": null,
      "width": 4000,
      "height": 3000,
      "padding": 0.25,
      "initial": { 3 keys },
      "backgroundColor": "#999999",
      "grid": { 8 keys },
      "tokenVision": true,
      "fog": { 3 keys },
      "environment": { 6 keys },
      "drawings": [],
      "tokens": [],
      "lights": [],
      "notes": [],
      "sounds": [],
      "regions": [],
      "templates": [],
      "tiles": [],
      "walls": [],
      "playlist": null,
      "playlistSound": null,
      "journal": null,
      "journalEntryPage": null,
      "weather": "",
      "folder": null,
      "sort": 0,
      "ownership": { 2 keys },
      "flags": {},
      "_stats": { 9 keys }
    },
    10: {
      "name": "test",
      "_id": "uisZmFzI2Tjh1xSA",
      "active": false,
      "navigation": true,
      "navOrder": 0,
      "background": { 11 keys },
      "foreground": null,
      "foregroundElevation": null,
      "thumb": null,
      "width": 4000,
      "height": 3000,
      "padding": 0.25,
      "initial": { 3 keys },
      "backgroundColor": "#999999",
      "grid": { 8 keys },
      "tokenVision": true,
      "fog": { 3 keys },
      "environment": { 6 keys },
      "drawings": [],
      "tokens": [],
      "lights": [],
      "notes": [],
      "sounds": [],
      "regions": [],
      "templates": [],
      "tiles": [],
      "walls": [],
      "playlist": null,
      "playlistSound": null,
      "journal": null,
      "journalEntryPage": null,
      "weather": "",
      "folder": null,
      "sort": 0,
      "ownership": { 2 keys },
      "flags": {},
      "_stats": { 9 keys }
    },
    11: {
      "name": "test",
      "_id": "v5E3y16p9juupLJS",
      "active": false,
      "navigation": true,
      "navOrder": 0,
      "background": { 11 keys },
      "foreground": null,
      "foregroundElevation": null,
      "thumb": null,
      "width": 4000,
      "height": 3000,
      "padding": 0.25,
      "initial": { 3 keys },
      "backgroundColor": "#999999",
      "grid": { 8 keys },
      "tokenVision": true,
      "fog": { 3 keys },
      "environment": { 6 keys },
      "drawings": [],
      "tokens": [],
      "lights": [],
      "notes": [],
      "sounds": [],
      "regions": [],
      "templates": [],
      "tiles": [],
      "walls": [],
      "playlist": null,
      "playlistSound": null,
      "journal": null,
      "journalEntryPage": null,
      "weather": "",
      "folder": null,
      "sort": 0,
      "ownership": { 2 keys },
      "flags": {},
      "_stats": { 9 keys }
    },
    12: {
      "grid": { 8 keys },
      "height": 1000,
      "name": "test-scene-updated",
      "width": 1000,
      "_id": "7iYl9ExwMdFm9POw",
      "active": false,
      "navigation": true,
      "navOrder": 0,
      "background": { 11 keys },
      "foreground": null,
      "foregroundElevation": null,
      "thumb": null,
      "padding": 0.25,
      "initial": { 3 keys },
      "backgroundColor": "#999999",
      "tokenVision": true,
      "fog": { 3 keys },
      "environment": { 6 keys },
      "drawings": [],
      "tokens": [],
      "lights": [],
      "notes": [],
      "sounds": [],
      "regions": [],
      "templates": [],
      "tiles": [],
      "walls": [],
      "playlist": null,
      "playlistSound": null,
      "journal": null,
      "journalEntryPage": null,
      "weather": "",
      "folder": null,
      "sort": 0,
      "ownership": { 2 keys },
      "flags": {},
      "_stats": { 9 keys }
    },
    13: {
      "grid": { 8 keys },
      "height": 1000,
      "name": "test-scene-updated",
      "width": 1000,
      "_id": "aQADc2ek0f7ls9af",
      "active": false,
      "navigation": true,
      "navOrder": 0,
      "background": { 11 keys },
      "foreground": null,
      "foregroundElevation": null,
      "thumb": null,
      "padding": 0.25,
      "initial": { 3 keys },
      "backgroundColor": "#999999",
      "tokenVision": true,
      "fog": { 3 keys },
      "environment": { 6 keys },
      "drawings": [],
      "tokens": [ 3 items ],
      "lights": [ 2 items ],
      "notes": [ 2 items ],
      "sounds": [ 2 items ],
      "regions": [],
      "templates": [ 2 items ],
      "tiles": [],
      "walls": [],
      "playlist": null,
      "playlistSound": null,
      "journal": null,
      "journalEntryPage": null,
      "weather": "",
      "folder": null,
      "sort": 0,
      "ownership": { 2 keys },
      "flags": {},
      "_stats": { 9 keys }
    },
    14: {
      "grid": { 8 keys },
      "height": 1000,
      "name": "test-scene-updated",
      "width": 1000,
      "_id": "cDiBNArUBdiC76Xd",
      "active": false,
      "navigation": true,
      "navOrder": 0,
      "background": { 11 keys },
      "foreground": null,
      "foregroundElevation": null,
      "thumb": null,
      "padding": 0.25,
      "initial": { 3 keys },
      "backgroundColor": "#999999",
      "tokenVision": true,
      "fog": { 3 keys },
      "environment": { 6 keys },
      "drawings": [],
      "tokens": [ 1 item ],
      "lights": [],
      "notes": [],
      "sounds": [],
      "regions": [],
      "templates": [],
      "tiles": [],
      "walls": [],
      "playlist": null,
      "playlistSound": null,
      "journal": null,
      "journalEntryPage": null,
      "weather": "",
      "folder": null,
      "sort": 0,
      "ownership": { 2 keys },
      "flags": {},
      "_stats": { 9 keys }
    },
    15: {
      "grid": { 8 keys },
      "height": 1000,
      "name": "test-scene-updated",
      "width": 1000,
      "_id": "oAo1nnXqH58UK6h4",
      "active": true,
      "navigation": true,
      "navOrder": 0,
      "background": { 11 keys },
      "foreground": null,
      "foregroundElevation": null,
      "thumb": null,
      "padding": 0.25,
      "initial": { 3 keys },
      "backgroundColor": "#999999",
      "tokenVision": true,
      "fog": { 3 keys },
      "environment": { 6 keys },
      "drawings": [],
      "tokens": [ 12 items ],
      "lights": [ 11 items ],
      "notes": [ 11 items ],
      "sounds": [ 11 items ],
      "regions": [],
      "templates": [ 11 items ],
      "tiles": [],
      "walls": [],
      "playlist": null,
      "playlistSound": null,
      "journal": null,
      "journalEntryPage": null,
      "weather": "",
      "folder": null,
      "sort": 0,
      "ownership": { 2 keys },
      "flags": {},
      "_stats": { 9 keys }
    },
    16: {
      "grid": { 8 keys },
      "height": 1000,
      "name": "test-scene-updated",
      "width": 1000,
      "_id": "pxk3rKsNgpwB6bG5",
      "active": false,
      "navigation": true,
      "navOrder": 0,
      "background": { 11 keys },
      "foreground": null,
      "foregroundElevation": null,
      "thumb": null,
      "padding": 0.25,
      "initial": { 3 keys },
      "backgroundColor": "#999999",
      "tokenVision": true,
      "fog": { 3 keys },
      "environment": { 6 keys },
      "drawings": [],
      "tokens": [],
      "lights": [],
      "notes": [],
      "sounds": [],
      "regions": [],
      "templates": [],
      "tiles": [],
      "walls": [],
      "playlist": null,
      "playlistSound": null,
      "journal": null,
      "journalEntryPage": null,
      "weather": "",
      "folder": null,
      "sort": 0,
      "ownership": { 2 keys },
      "flags": {},
      "_stats": { 9 keys }
    },
    17: {
      "grid": { 8 keys },
      "height": 1000,
      "name": "test-scene-updated",
      "width": 1000,
      "_id": "vCLJOw0STWGphIWU",
      "active": false,
      "navigation": true,
      "navOrder": 0,
      "background": { 11 keys },
      "foreground": null,
      "foregroundElevation": null,
      "thumb": null,
      "padding": 0.25,
      "initial": { 3 keys },
      "backgroundColor": "#999999",
      "tokenVision": true,
      "fog": { 3 keys },
      "environment": { 6 keys },
      "drawings": [],
      "tokens": [ 3 items ],
      "lights": [ 2 items ],
      "notes": [ 2 items ],
      "sounds": [ 2 items ],
      "regions": [],
      "templates": [ 2 items ],
      "tiles": [],
      "walls": [ 1 item ],
      "playlist": null,
      "playlistSound": null,
      "journal": null,
      "journalEntryPage": null,
      "weather": "",
      "folder": null,
      "sort": 0,
      "ownership": { 2 keys },
      "flags": {},
      "_stats": { 9 keys },
      "navName": ""
    },
    18: {
      "name": "test",
      "_id": "InuAccGQ1wWqwPfm",
      "active": false,
      "navigation": true,
      "navOrder": 0,
      "background": { 11 keys },
      "foreground": null,
      "foregroundElevation": null,
      "thumb": null,
      "width": 4000,
      "height": 3000,
      "padding": 0.25,
      "initial": { 3 keys },
      "backgroundColor": "#999999",
      "grid": { 8 keys },
      "tokenVision": true,
      "fog": { 3 keys },
      "environment": { 6 keys },
      "drawings": [],
      "tokens": [],
      "lights": [],
      "notes": [],
      "sounds": [],
      "regions": [],
      "templates": [],
      "tiles": [],
      "walls": [],
      "playlist": null,
      "playlistSound": null,
      "journal": null,
      "journalEntryPage": null,
      "weather": "",
      "folder": null,
      "sort": 0,
      "ownership": { 2 keys },
      "flags": {},
      "_stats": { 9 keys }
    },
    19: {
      "grid": { 8 keys },
      "height": 1000,
      "name": "test-scene",
      "width": 1000,
      "_id": "tgYnjCnq6EFiREjl",
      "active": false,
      "navigation": true,
      "navOrder": 0,
      "background": { 11 keys },
      "foreground": null,
      "foregroundElevation": null,
      "thumb": null,
      "padding": 0.25,
      "initial": { 3 keys },
      "backgroundColor": "#999999",
      "tokenVision": true,
      "fog": { 3 keys },
      "environment": { 6 keys },
      "drawings": [],
      "tokens": [],
      "lights": [],
      "notes": [],
      "sounds": [],
      "regions": [],
      "templates": [],
      "tiles": [],
      "walls": [],
      "playlist": null,
      "playlistSound": null,
      "journal": null,
      "journalEntryPage": null,
      "weather": "",
      "folder": null,
      "sort": 0,
      "ownership": { 2 keys },
      "flags": {},
      "_stats": { 9 keys }
    },
    20: {
      "height": 500,
      "name": "test-scene-expendable",
      "width": 500,
      "_id": "YlMB7AjPvDJfbNjh",
      "active": false,
      "navigation": true,
      "navOrder": 0,
      "background": { 11 keys },
      "foreground": null,
      "foregroundElevation": null,
      "thumb": null,
      "padding": 0.25,
      "initial": { 3 keys },
      "backgroundColor": "#999999",
      "grid": { 8 keys },
      "tokenVision": true,
      "fog": { 3 keys },
      "environment": { 6 keys },
      "drawings": [],
      "tokens": [],
      "lights": [],
      "notes": [],
      "sounds": [],
      "regions": [],
      "templates": [],
      "tiles": [],
      "walls": [],
      "playlist": null,
      "playlistSound": null,
      "journal": null,
      "journalEntryPage": null,
      "weather": "",
      "folder": null,
      "sort": 0,
      "ownership": { 2 keys },
      "flags": {},
      "_stats": { 9 keys }
    }
  ]
}

GET /scene/image/raw

Get the raw background image of a scene

Returns the scene's background image file without any tokens, lights, or other canvas elements rendered on it.

Required scope: scene:read

Parameters

Name	Type	Source	Description
clientId	string	query	Client ID for the Foundry world
sceneId	string	body, query	Scene ID (defaults to viewed/active scene)
active	boolean	body, query	If true, explicitly use the player-facing active scene instead of the viewed scene
userId	string	query, body	Foundry user ID or username to scope permissions (omit for GM-level access)

Returns

binary - The raw scene background image

Try It Out

POST /scene

Create a new scene

Required scope: scene:write

Parameters

Name	Type	Required	Source	Description
data	object	✓	body	Scene data object (name, width, height, grid, etc.)
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

object - Created scene data

Try It Out

Code Examples

JavaScript
cURL
Python
TypeScript
Emojicode

const baseUrl = 'http://localhost:3010';
const path = '/scene';
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({
      "data": {
        "name": "test-scene",
        "width": 1000,
        "height": 1000,
        "grid": {
          "size": 100
        }
      }
    })
});
const data = await response.json();
console.log(data);

curl -X POST 'http://localhost:3010/scene?clientId=fvtt_099ad17ea199e7e3' \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"data":{"name":"test-scene","width":1000,"height":1000,"grid":{"size":100}}}'

import requests

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

response = requests.post(
    url,
    params=params,
    headers={
        'x-api-key': 'your-api-key-here'
    },
    json={
      "data": {
        "name": "test-scene",
        "width": 1000,
        "height": 1000,
        "grid": {
          "size": 100
        }
      }
    }
)
data = response.json()
print(data)

import axios from 'axios';

(async () => {
  const baseUrl = 'http://localhost:3010';
  const path = '/scene';
  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: {
        "data": {
          "name": "test-scene",
          "width": 1000,
          "height": 1000,
          "grid": {
            "size": 100
          }
        }
      }
  });
  const data = response.data;
  console.log(data);
})();

📦 sockets 🏠

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

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

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

  💭 Request body
  🔤{"data":{"name":"test-scene","width":1000,"height":1000,"grid":{"size":100}}}🔤 ➡️ body

  💭 Build HTTP request
  🔤POST /scene🧲queryString🧲 HTTP/1.1❌r❌nHost: localhost:3010❌r❌nx-api-key: your-api-key-here❌r❌nContent-Type: application/json❌r❌nContent-Length: 77❌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": "create-scene-result",
  "requestId": "create-scene_1778896417795",
  "data": {
    "grid": {
      "size": 100,
      "type": 1,
      "style": "solidLines",
      "thickness": 1,
      "color": "#000000",
      "alpha": 0.2,
      "distance": 5,
      "units": "ft"
    },
    "height": 1000,
    "name": "test-scene",
    "width": 1000,
    "_id": "tgYnjCnq6EFiREjl",
    "active": false,
    "navigation": true,
    "navOrder": 0,
    "background": {
      "src": null,
      "anchorX": 0,
      "anchorY": 0,
      "offsetX": 0,
      "offsetY": 0,
      "fit": "fill",
      "scaleX": 1,
      "scaleY": 1,
      "rotation": 0,
      "tint": "#ffffff",
      "alphaThreshold": 0
    },
    "foreground": null,
    "foregroundElevation": null,
    "thumb": null,
    "padding": 0.25,
    "initial": {
      "x": null,
      "y": null,
      "scale": null
    },
    "backgroundColor": "#999999",
    "tokenVision": true,
    "fog": {
      "exploration": true,
      "overlay": null,
      "colors": { 2 keys }
    },
    "environment": {
      "darknessLevel": 0,
      "darknessLock": false,
      "globalLight": { 10 keys },
      "cycle": true,
      "base": { 5 keys },
      "dark": { 5 keys }
    },
    "drawings": [],
    "tokens": [],
    "lights": [],
    "notes": [],
    "sounds": [],
    "regions": [],
    "templates": [],
    "tiles": [],
    "walls": [],
    "playlist": null,
    "playlistSound": null,
    "journal": null,
    "journalEntryPage": null,
    "weather": "",
    "folder": null,
    "sort": 0,
    "ownership": {
      "default": 0,
      "r6bXhB7k9cXa3cif": 3
    },
    "flags": {},
    "_stats": {
      "compendiumSource": null,
      "duplicateSource": null,
      "exportSource": null,
      "coreVersion": "13.348",
      "systemId": "dnd5e",
      "systemVersion": "5.0.4",
      "createdTime": 1778896417797,
      "modifiedTime": 1778896417797,
      "lastModifiedBy": "r6bXhB7k9cXa3cif"
    }
  }
}

PUT /scene

Update an existing scene

Required scope: scene:write

Parameters

Name	Type	Required	Source	Description
data	object	✓	body	Object containing the scene fields to update
clientId	string		query	Client ID for the Foundry world
sceneId	string		body, query	ID of the scene to update
name	string		body, query	Name of the scene to update (alternative to sceneId)
active	boolean		body, query	Set to true to target the active scene
userId	string		query, body	Foundry user ID or username to scope permissions (omit for GM-level access)

Returns

object - Updated scene data

Try It Out

Code Examples

JavaScript
cURL
Python
TypeScript
Emojicode

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

const response = await fetch(url, {
  method: 'PUT',
  headers: {
    'x-api-key': 'your-api-key-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
      "sceneId": "tgYnjCnq6EFiREjl",
      "data": {
        "name": "test-scene-updated"
      }
    })
});
const data = await response.json();
console.log(data);

curl -X PUT 'http://localhost:3010/scene?clientId=fvtt_099ad17ea199e7e3' \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"sceneId":"tgYnjCnq6EFiREjl","data":{"name":"test-scene-updated"}}'

import requests

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

response = requests.put(
    url,
    params=params,
    headers={
        'x-api-key': 'your-api-key-here'
    },
    json={
      "sceneId": "tgYnjCnq6EFiREjl",
      "data": {
        "name": "test-scene-updated"
      }
    }
)
data = response.json()
print(data)

import axios from 'axios';

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

  const response = await axios({
    method: 'put',
    headers: {
      'x-api-key': 'your-api-key-here',
      'Content-Type': 'application/json'
    },
    url,
    data: {
        "sceneId": "tgYnjCnq6EFiREjl",
        "data": {
          "name": "test-scene-updated"
        }
      }
  });
  const data = response.data;
  console.log(data);
})();

📦 sockets 🏠

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

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

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

  💭 Request body
  🔤{"sceneId":"tgYnjCnq6EFiREjl","data":{"name":"test-scene-updated"}}🔤 ➡️ body

  💭 Build HTTP request
  🔤PUT /scene🧲queryString🧲 HTTP/1.1❌r❌nHost: localhost:3010❌r❌nx-api-key: your-api-key-here❌r❌nContent-Type: application/json❌r❌nContent-Length: 67❌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": "update-scene-result",
  "requestId": "update-scene_1778896417824",
  "data": {
    "grid": {
      "size": 100,
      "type": 1,
      "style": "solidLines",
      "thickness": 1,
      "color": "#000000",
      "alpha": 0.2,
      "distance": 5,
      "units": "ft"
    },
    "height": 1000,
    "name": "test-scene-updated",
    "width": 1000,
    "_id": "tgYnjCnq6EFiREjl",
    "active": false,
    "navigation": true,
    "navOrder": 0,
    "background": {
      "src": null,
      "anchorX": 0,
      "anchorY": 0,
      "offsetX": 0,
      "offsetY": 0,
      "fit": "fill",
      "scaleX": 1,
      "scaleY": 1,
      "rotation": 0,
      "tint": "#ffffff",
      "alphaThreshold": 0
    },
    "foreground": null,
    "foregroundElevation": null,
    "thumb": null,
    "padding": 0.25,
    "initial": {
      "x": null,
      "y": null,
      "scale": null
    },
    "backgroundColor": "#999999",
    "tokenVision": true,
    "fog": {
      "exploration": true,
      "overlay": null,
      "colors": { 2 keys }
    },
    "environment": {
      "darknessLevel": 0,
      "darknessLock": false,
      "globalLight": { 10 keys },
      "cycle": true,
      "base": { 5 keys },
      "dark": { 5 keys }
    },
    "drawings": [],
    "tokens": [],
    "lights": [],
    "notes": [],
    "sounds": [],
    "regions": [],
    "templates": [],
    "tiles": [],
    "walls": [],
    "playlist": null,
    "playlistSound": null,
    "journal": null,
    "journalEntryPage": null,
    "weather": "",
    "folder": null,
    "sort": 0,
    "ownership": {
      "default": 0,
      "r6bXhB7k9cXa3cif": 3
    },
    "flags": {},
    "_stats": {
      "compendiumSource": null,
      "duplicateSource": null,
      "exportSource": null,
      "coreVersion": "13.348",
      "systemId": "dnd5e",
      "systemVersion": "5.0.4",
      "createdTime": 1778896417797,
      "modifiedTime": 1778896417825,
      "lastModifiedBy": "r6bXhB7k9cXa3cif"
    }
  }
}

DELETE /scene

Delete a scene

Required scope: scene:write

Parameters

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

Returns

object - Deletion result

Try It Out

Code Examples

JavaScript
cURL
Python
TypeScript
Emojicode

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

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

curl -X DELETE 'http://localhost:3010/scene?clientId=fvtt_099ad17ea199e7e3&sceneId=YlMB7AjPvDJfbNjh' \
  -H "x-api-key: your-api-key-here"

import requests

base_url = 'http://localhost:3010'
path = '/scene'
params = {
    'clientId': 'fvtt_099ad17ea199e7e3',
    'sceneId': 'YlMB7AjPvDJfbNjh'
}
url = f'{base_url}{path}'

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

import axios from 'axios';

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

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

📦 sockets 🏠

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

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

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

  💭 Build HTTP request
  🔤DELETE /scene🧲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": "delete-scene-result",
  "requestId": "delete-scene_1778896422861",
  "success": true
}

POST /switch-scene

Switch the active scene

Required scope: scene:write

Parameters

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

Returns

object - Result of the scene switch

Try It Out

Code Examples

JavaScript
cURL
Python
TypeScript
Emojicode

const baseUrl = 'http://localhost:3010';
const path = '/switch-scene';
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({
      "sceneId": "tgYnjCnq6EFiREjl"
    })
});
const data = await response.json();
console.log(data);

curl -X POST 'http://localhost:3010/switch-scene?clientId=fvtt_099ad17ea199e7e3' \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"sceneId":"tgYnjCnq6EFiREjl"}'

import requests

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

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

import axios from 'axios';

(async () => {
  const baseUrl = 'http://localhost:3010';
  const path = '/switch-scene';
  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: {
        "sceneId": "tgYnjCnq6EFiREjl"
      }
  });
  const data = response.data;
  console.log(data);
})();

📦 sockets 🏠

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

🏁 🍇
  💭 Connection settings
  🔤localhost🔤 ➡️ host
  3010 ➡️ port
  🔤/switch-scene🔤 ➡️ path

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

  💭 Request body
  🔤{"sceneId":"tgYnjCnq6EFiREjl"}🔤 ➡️ body

  💭 Build HTTP request
  🔤POST /switch-scene🧲queryString🧲 HTTP/1.1❌r❌nHost: localhost:3010❌r❌nx-api-key: your-api-key-here❌r❌nContent-Type: application/json❌r❌nContent-Length: 30❌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": "switch-scene-result",
  "requestId": "switch-scene_1778896417830",
  "success": true,
  "data": {
    "grid": {
      "size": 100,
      "type": 1,
      "style": "solidLines",
      "thickness": 1,
      "color": "#000000",
      "alpha": 0.2,
      "distance": 5,
      "units": "ft"
    },
    "height": 1000,
    "name": "test-scene-updated",
    "width": 1000,
    "_id": "tgYnjCnq6EFiREjl",
    "active": true,
    "navigation": true,
    "navOrder": 0,
    "background": {
      "src": null,
      "anchorX": 0,
      "anchorY": 0,
      "offsetX": 0,
      "offsetY": 0,
      "fit": "fill",
      "scaleX": 1,
      "scaleY": 1,
      "rotation": 0,
      "tint": "#ffffff",
      "alphaThreshold": 0
    },
    "foreground": null,
    "foregroundElevation": null,
    "thumb": null,
    "padding": 0.25,
    "initial": {
      "x": null,
      "y": null,
      "scale": null
    },
    "backgroundColor": "#999999",
    "tokenVision": true,
    "fog": {
      "exploration": true,
      "overlay": null,
      "colors": { 2 keys }
    },
    "environment": {
      "darknessLevel": 0,
      "darknessLock": false,
      "globalLight": { 10 keys },
      "cycle": true,
      "base": { 5 keys },
      "dark": { 5 keys }
    },
    "drawings": [],
    "tokens": [],
    "lights": [],
    "notes": [],
    "sounds": [],
    "regions": [],
    "templates": [],
    "tiles": [],
    "walls": [],
    "playlist": null,
    "playlistSound": null,
    "journal": null,
    "journalEntryPage": null,
    "weather": "",
    "folder": null,
    "sort": 0,
    "ownership": {
      "default": 0,
      "r6bXhB7k9cXa3cif": 3
    },
    "flags": {},
    "_stats": {
      "compendiumSource": null,
      "duplicateSource": null,
      "exportSource": null,
      "coreVersion": "13.348",
      "systemId": "dnd5e",
      "systemVersion": "5.0.4",
      "createdTime": 1778896417797,
      "modifiedTime": 1778896417833,
      "lastModifiedBy": "r6bXhB7k9cXa3cif"
    }
  }
}

GET /scene/image

Get a rendered screenshot of a scene

Captures the full rendered canvas of a scene including all visible layers (tokens, lights, walls, etc.) as an image. The scene can be specified by ID or defaults to the active scene.

Required scope: scene:read

Parameters

Name	Type	Source	Description
sceneId	string	query	Scene ID (defaults to viewed/active scene)
active	boolean	query	If true, explicitly use the player-facing active scene instead of the viewed scene
clientId	string	query	Client ID for the Foundry world
format	string	query	Image format: png or jpeg (default: png)
quality	number	query	Image quality 0-1 for JPEG (default: 0.9)
viewport	boolean	query	If true, capture exactly what the browser currently shows instead of the full scene
width	number	query	Output image width in pixels (default: scene width)
height	number	query	Output image height in pixels (default: scene height)
showGrid	boolean	query	Include grid lines in capture (default: false)
hideOverlays	boolean	query	Hide fog of war, weather, vision, and UI overlays (default: false)
userId	string	query	Foundry user ID or username

Returns

binary - The scene screenshot as an image

GET /scene​

Parameters​

Returns​

Try It Out​

Code Examples​

Response​

GET /scene/image/raw​

Parameters​

Returns​

Try It Out​

POST /scene​

Parameters​

Returns​

Try It Out​

Code Examples​

Response​

PUT /scene​

Parameters​

Returns​

Try It Out​

Code Examples​

Response​

DELETE /scene​

Parameters​

Returns​

Try It Out​

Code Examples​

Response​

POST /switch-scene​

Parameters​

Returns​

Try It Out​

Code Examples​

Response​

GET /scene/image​

Parameters​

Returns​

Try It Out​

GET /scene

Parameters

Returns

Try It Out

Code Examples

Response

GET /scene/image/raw

Parameters

Returns

Try It Out

POST /scene

Parameters

Returns

Try It Out

Code Examples

Response

PUT /scene

Parameters

Returns

Try It Out

Code Examples

Response

DELETE /scene

Parameters

Returns

Try It Out

Code Examples

Response

POST /switch-scene

Parameters

Returns

Try It Out

Code Examples

Response

GET /scene/image

Parameters

Returns

Try It Out