Utility

POST /select

Select token(s)

Selects one or more tokens in the Foundry VTT client.

Required scope: entity:read

Parameters

Name	Type	Source	Description
clientId	string	query	Client ID for the Foundry world
uuids	array	body	Array of UUIDs to select
name	string	body	Name of the token(s) to select
data	object	body	Data to match for selection (e.g., "data.attributes.hp.value": 20)
overwrite	boolean	body	Whether to overwrite existing selection
all	boolean	body	Whether to select all tokens on the canvas
userId	string	query, body	Foundry user ID or username to scope permissions (omit for GM-level access)

Returns

object - The selected token(s)

Try It Out

Code Examples

JavaScript
cURL
Python
TypeScript
Emojicode

const baseUrl = 'http://localhost:3010';
const path = '/select';
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({
      "all": true,
      "overwrite": true
    })
});
const data = await response.json();
console.log(data);

curl -X POST 'http://localhost:3010/select?clientId=fvtt_099ad17ea199e7e3' \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"all":true,"overwrite":true}'

import requests

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

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

import axios from 'axios';

(async () => {
  const baseUrl = 'http://localhost:3010';
  const path = '/select';
  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: {
        "all": true,
        "overwrite": true
      }
  });
  const data = response.data;
  console.log(data);
})();

📦 sockets 🏠

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

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

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

  💭 Request body
  🔤{"all":true,"overwrite":true}🔤 ➡️ body

  💭 Build HTTP request
  🔤POST /select🧲queryString🧲 HTTP/1.1❌r❌nHost: localhost:3010❌r❌nx-api-key: your-api-key-here❌r❌nContent-Type: application/json❌r❌nContent-Length: 29❌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": "select-result",
  "requestId": "select_1778896436279",
  "success": true,
  "count": 1,
  "message": "1 entities selected",
  "selected": [
    0: "Scene.tgYnjCnq6EFiREjl.Token.TOInpAfNZ6GRAJaG"
  ]
}

GET /selected

Get selected token(s)

Retrieves the currently selected token(s) in the Foundry VTT client.

Required scope: entity:read

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

object - The selected token(s)

Try It Out

Code Examples

JavaScript
cURL
Python
TypeScript
Emojicode

const baseUrl = 'http://localhost:3010';
const path = '/selected';
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 -X GET 'http://localhost:3010/selected?clientId=fvtt_099ad17ea199e7e3' \
  -H "x-api-key: your-api-key-here"

import requests

base_url = 'http://localhost:3010'
path = '/selected'
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)

import axios from 'axios';

(async () => {
  const baseUrl = 'http://localhost:3010';
  const path = '/selected';
  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);
})();

📦 sockets 🏠

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

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

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

  💭 Build HTTP request
  🔤GET /selected🧲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": "selected-result",
  "requestId": "selected_1778896436283",
  "success": true,
  "selected": [
    0: {
      "tokenUuid": "Scene.tgYnjCnq6EFiREjl.Token.TOInpAfNZ6GRAJaG",
      "actorUuid": "Scene.tgYnjCnq6EFiREjl.Token.TOInpAfNZ6GRAJaG.Actor.S6Nh5SfYPcyyUhRg"
    }
  ]
}

GET /players

Get players/users

Retrieves a list of all users configured in the Foundry VTT world. Useful for discovering valid userId values for permission-scoped API calls.

Required scope: entity:read

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

object - List of users with their IDs, names, roles, and active status

Try It Out

Code Examples

JavaScript
cURL
Python
TypeScript
Emojicode

const baseUrl = 'http://localhost:3010';
const path = '/players';
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 -X GET 'http://localhost:3010/players?clientId=fvtt_099ad17ea199e7e3' \
  -H "x-api-key: your-api-key-here"

import requests

base_url = 'http://localhost:3010'
path = '/players'
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)

import axios from 'axios';

(async () => {
  const baseUrl = 'http://localhost:3010';
  const path = '/players';
  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);
})();

📦 sockets 🏠

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

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

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

  💭 Build HTTP request
  🔤GET /players🧲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": "players-result",
  "requestId": "players_1778896436289",
  "users": [
    0: {
      "id": "5ypAoBvOiyjDKiaZ",
      "name": "Gamemaster",
      "role": 4,
      "isGM": true,
      "active": false,
      "color": "#28cca2",
      "avatar": "icons/svg/mystery-man.svg"
    },
    1: {
      "id": "r6bXhB7k9cXa3cif",
      "name": "tester",
      "role": 4,
      "isGM": true,
      "active": true,
      "color": "#cc2829",
      "avatar": "icons/svg/mystery-man.svg"
    },
    2: {
      "id": "XQP35eYL5dUPscgE",
      "name": "s2s-test-2",
      "role": 1,
      "isGM": false,
      "active": false,
      "color": "#a0cc28",
      "avatar": "icons/svg/mystery-man.svg"
    },
    3: {
      "id": "JLfKTeTgCDpAdDfw",
      "name": "some-cool-guy",
      "role": 1,
      "isGM": false,
      "active": false,
      "color": "#6328cc",
      "avatar": "icons/svg/mystery-man.svg"
    },
    4: {
      "id": "NIY9RLVBVRZgBH66",
      "name": "test",
      "role": 1,
      "isGM": false,
      "active": false,
      "color": "#cc6328",
      "avatar": "icons/svg/mystery-man.svg"
    }
  ]
}

GET /world-info

Get comprehensive world information

Returns a single object with world name, game system, Foundry version, all modules (with active status), all users (with online status), and the active scene. Useful for API clients to discover the world state.

Required scope: world:info

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

object - World information object

Try It Out

Code Examples

JavaScript
cURL
Python
TypeScript
Emojicode

const baseUrl = 'http://localhost:3010';
const path = '/world-info';
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 -X GET 'http://localhost:3010/world-info?clientId=fvtt_099ad17ea199e7e3' \
  -H "x-api-key: your-api-key-here"

import requests

base_url = 'http://localhost:3010'
path = '/world-info'
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)

import axios from 'axios';

(async () => {
  const baseUrl = 'http://localhost:3010';
  const path = '/world-info';
  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);
})();

📦 sockets 🏠

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

🏁 🍇
  💭 Connection settings
  🔤localhost🔤 ➡️ host
  3010 ➡️ port
  🔤/world-info🔤 ➡️ path

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

  💭 Build HTTP request
  🔤GET /world-info🧲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": "world-info-result",
  "requestId": "world-info_1778896436294",
  "data": {
    "world": {
      "id": "testing",
      "title": "testing"
    },
    "system": {
      "id": "dnd5e",
      "title": "Dungeons & Dragons Fifth Edition",
      "version": "5.0.4"
    },
    "foundryVersion": "13.348",
    "modules": [
      0: { 4 keys },
      1: { 4 keys },
      2: { 4 keys },
      3: { 4 keys },
      4: { 4 keys },
      5: { 4 keys },
      6: { 4 keys },
      7: { 4 keys },
      8: { 4 keys },
      9: { 4 keys },
      10: { 4 keys },
      11: { 4 keys },
      12: { 4 keys },
      13: { 4 keys },
      14: { 4 keys },
      15: { 4 keys },
      16: { 4 keys },
      17: { 4 keys },
      18: { 4 keys },
      19: { 4 keys },
      20: { 4 keys },
      21: { 4 keys },
      22: { 4 keys },
      23: { 4 keys },
      24: { 4 keys },
      25: { 4 keys },
      26: { 4 keys },
      27: { 4 keys },
      28: { 4 keys },
      29: { 4 keys },
      30: { 4 keys },
      31: { 4 keys },
      32: { 4 keys },
      33: { 4 keys },
      34: { 4 keys },
      35: { 4 keys },
      36: { 4 keys },
      37: { 4 keys },
      38: { 4 keys },
      39: { 4 keys },
      40: { 4 keys },
      41: { 4 keys },
      42: { 4 keys },
      43: { 4 keys },
      44: { 4 keys },
      45: { 4 keys },
      46: { 4 keys },
      47: { 4 keys },
      48: { 4 keys },
      49: { 4 keys },
      50: { 4 keys },
      51: { 4 keys },
      52: { 4 keys },
      53: { 4 keys },
      54: { 4 keys },
      55: { 4 keys },
      56: { 4 keys },
      57: { 4 keys },
      58: { 4 keys },
      59: { 4 keys },
      60: { 4 keys },
      61: { 4 keys },
      62: { 4 keys },
      63: { 4 keys },
      64: { 4 keys },
      65: { 4 keys },
      66: { 4 keys },
      67: { 4 keys },
      68: { 4 keys },
      69: { 4 keys },
      70: { 4 keys },
      71: { 4 keys },
      72: { 4 keys },
      73: { 4 keys },
      74: { 4 keys },
      75: { 4 keys },
      76: { 4 keys },
      77: { 4 keys },
      78: { 4 keys },
      79: { 4 keys },
      80: { 4 keys },
      81: { 4 keys },
      82: { 4 keys },
      83: { 4 keys },
      84: { 4 keys },
      85: { 4 keys },
      86: { 4 keys },
      87: { 4 keys },
      88: { 4 keys },
      89: { 4 keys },
      90: { 4 keys },
      91: { 4 keys },
      92: { 4 keys },
      93: { 4 keys },
      94: { 4 keys },
      95: { 4 keys },
      96: { 4 keys },
      97: { 4 keys },
      98: { 4 keys },
      99: { 4 keys },
      100: { 4 keys },
      101: { 4 keys },
      102: { 4 keys },
      103: { 4 keys },
      104: { 4 keys },
      105: { 4 keys },
      106: { 4 keys },
      107: { 4 keys },
      108: { 4 keys },
      109: { 4 keys },
      110: { 4 keys },
      111: { 4 keys },
      112: { 4 keys },
      113: { 4 keys },
      114: { 4 keys },
      115: { 4 keys },
      116: { 4 keys },
      117: { 4 keys },
      118: { 4 keys },
      119: { 4 keys },
      120: { 4 keys },
      121: { 4 keys },
      122: { 4 keys },
      123: { 4 keys },
      124: { 4 keys },
      125: { 4 keys },
      126: { 4 keys },
      127: { 4 keys },
      128: { 4 keys },
      129: { 4 keys },
      130: { 4 keys },
      131: { 4 keys },
      132: { 4 keys },
      133: { 4 keys },
      134: { 4 keys },
      135: { 4 keys },
      136: { 4 keys },
      137: { 4 keys },
      138: { 4 keys },
      139: { 4 keys },
      140: { 4 keys },
      141: { 4 keys },
      142: { 4 keys },
      143: { 4 keys },
      144: { 4 keys },
      145: { 4 keys }
    ],
    "users": [
      0: { 7 keys },
      1: { 7 keys },
      2: { 7 keys },
      3: { 7 keys },
      4: { 7 keys }
    ],
    "activeScene": {
      "id": "tgYnjCnq6EFiREjl",
      "name": "test-scene-updated"
    }
  }
}

POST /execute-js

Execute JavaScript

Executes a JavaScript script in the Foundry VTT client.

Required scope: execute-js

Parameters

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

Returns

object - The result of the executed script

Try It Out

Code Examples

JavaScript
cURL
Python
TypeScript
Emojicode

const baseUrl = 'http://localhost:3010';
const path = '/execute-js';
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({
      "script": "const wsRelayUrl=game.settings.get(\"foundry-rest-api\", \"wsRelayUrl\");return wsRelayUrl;"
    })
});
const data = await response.json();
console.log(data);

curl -X POST 'http://localhost:3010/execute-js?clientId=fvtt_099ad17ea199e7e3' \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"script":"const wsRelayUrl=game.settings.get(\"foundry-rest-api\", \"wsRelayUrl\");return wsRelayUrl;"}'

import requests

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

response = requests.post(
    url,
    params=params,
    headers={
        'x-api-key': 'your-api-key-here'
    },
    json={
      "script": "const wsRelayUrl=game.settings.get(\"foundry-rest-api\", \"wsRelayUrl\");return wsRelayUrl;"
    }
)
data = response.json()
print(data)

import axios from 'axios';

(async () => {
  const baseUrl = 'http://localhost:3010';
  const path = '/execute-js';
  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: {
        "script": "const wsRelayUrl=game.settings.get(\"foundry-rest-api\", \"wsRelayUrl\");return wsRelayUrl;"
      }
  });
  const data = response.data;
  console.log(data);
})();

📦 sockets 🏠

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

🏁 🍇
  💭 Connection settings
  🔤localhost🔤 ➡️ host
  3010 ➡️ port
  🔤/execute-js🔤 ➡️ path

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

  💭 Request body
  🔤{"script":"const wsRelayUrl=game.settings.get(\"foundry-rest-api\", \"wsRelayUrl\");return wsRelayUrl;"}🔤 ➡️ body

  💭 Build HTTP request
  🔤POST /execute-js🧲queryString🧲 HTTP/1.1❌r❌nHost: localhost:3010❌r❌nx-api-key: your-api-key-here❌r❌nContent-Type: application/json❌r❌nContent-Length: 104❌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": "execute-js-result",
  "requestId": "execute-js_1778896436291",
  "success": true,
  "result": "ws://localhost:3010/relay"
}

POST /select​

Parameters​

Returns​

Try It Out​

Code Examples​

Response​

GET /selected​

Parameters​

Returns​

Try It Out​

Code Examples​

Response​

GET /players​

Parameters​

Returns​

Try It Out​

Code Examples​

Response​

GET /world-info​

Parameters​

Returns​

Try It Out​

Code Examples​

Response​

POST /execute-js​

Parameters​

Returns​

Try It Out​

Code Examples​

Response​

POST /select

Parameters

Returns

Try It Out

Code Examples

Response

GET /selected

Parameters

Returns

Try It Out

Code Examples

Response

GET /players

Parameters

Returns

Try It Out

Code Examples

Response

GET /world-info

Parameters

Returns

Try It Out

Code Examples

Response

POST /execute-js

Parameters

Returns

Try It Out

Code Examples

Response