Utility
POST /select
Select token(s)
Selects one or more tokens in the Foundry VTT client.
Parameters
| Name | Type | Required | 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
GET /selected
Get selected token(s)
Retrieves the currently selected token(s) in the Foundry VTT client.
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
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.
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
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.
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
POST /execute-js
Execute JavaScript
Executes a JavaScript script in the Foundry VTT client.
Parameters
| Name | Type | Required | 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