User

GET /users

List all Foundry users

Retrieves a list of all users configured in the Foundry VTT world, including their roles and online status. This is a GM-only operation.

Required scope: user: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

array - Array of user objects with id, name, role, isGM, active, color, avatar, and character fields

Try It Out

Code Examples

JavaScript
cURL
Python
TypeScript
Emojicode

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

import requests

base_url = 'http://localhost:3010'
path = '/users'
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 = '/users';
  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
  🔤/users🔤 ➡️ path

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

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

GET /user

Get a single Foundry user

Retrieves a single user by their ID or name. This is a GM-only operation.

Required scope: user:read

Parameters

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

Returns

object - User object with id, name, role, isGM, active, color, avatar, and character fields

Try It Out

Code Examples

JavaScript
cURL
Python
TypeScript
Emojicode

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

import requests

base_url = 'http://localhost:3010'
path = '/user'
params = {
    'clientId': 'fvtt_099ad17ea199e7e3',
    'id': '7odiSNcQcQ6jG68g'
}
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 = '/user';
  const params = {
    clientId: 'fvtt_099ad17ea199e7e3',
    id: '7odiSNcQcQ6jG68g'
  };
  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
  🔤/user🔤 ➡️ path

  💭 Query parameters
  🔤clientId=fvtt_099ad17ea199e7e3🔤 ➡️ clientId
  🔤id=7odiSNcQcQ6jG68g🔤 ➡️ id
  🔤?🧲clientId🧲&🧲id🧲🔤 ➡️ queryString

  💭 Build HTTP request
  🔤GET /user🧲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-user-result",
  "requestId": "get-user_1778896442215",
  "data": {
    "id": "7odiSNcQcQ6jG68g",
    "name": "test-api-user",
    "role": 1,
    "isGM": false,
    "active": false,
    "color": "#28cc4c",
    "avatar": "icons/svg/mystery-man.svg",
    "character": null
  }
}

POST /user

Create a new Foundry user

Creates a new user in the Foundry VTT world with the specified name, role, and optional password. This is a GM-only operation.

Required scope: user:write

Parameters

Name	Type	Required	Source	Description
name	string	✓	body	Username for the new user
clientId	string		query	Client ID for the Foundry world
role	number		body	User role: 0=None, 1=Player, 2=Trusted, 3=Assistant, 4=GM (default: 1)
password	string		body	Password for the new user
userId	string		query, body	Foundry user ID or username to scope permissions (omit for GM-level access)

Returns

object - The created user object

Try It Out

Code Examples

JavaScript
cURL
Python
TypeScript
Emojicode

const baseUrl = 'http://localhost:3010';
const path = '/user';
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({
      "name": "test-api-user",
      "role": 1,
      "password": "your-password-here"
    })
});
const data = await response.json();
console.log(data);

curl -X POST 'http://localhost:3010/user?clientId=fvtt_099ad17ea199e7e3' \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"name":"test-api-user","role":1,"password": "your-password-here"}'

import requests

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

response = requests.post(
    url,
    params=params,
    headers={
        'x-api-key': 'your-api-key-here'
    },
    json={
      "name": "test-api-user",
      "role": 1,
      "password": "your-password-here"
    }
)
data = response.json()
print(data)

import axios from 'axios';

(async () => {
  const baseUrl = 'http://localhost:3010';
  const path = '/user';
  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: {
        "name": "test-api-user",
        "role": 1,
        "password": "your-password-here"
      }
  });
  const data = response.data;
  console.log(data);
})();

📦 sockets 🏠

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

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

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

  💭 Request body
  🔤{"name":"test-api-user","role":1,"password": "your-password-here"}🔤 ➡️ body

  💭 Build HTTP request
  🔤POST /user🧲queryString🧲 HTTP/1.1❌r❌nHost: localhost:3010❌r❌nx-api-key: your-api-key-here❌r❌nContent-Type: application/json❌r❌nContent-Length: 62❌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-user-result",
  "requestId": "create-user_1778896442206",
  "data": {
    "id": "7odiSNcQcQ6jG68g",
    "name": "test-api-user",
    "role": 1,
    "isGM": false,
    "active": false,
    "color": "#28cc4c",
    "avatar": "icons/svg/mystery-man.svg",
    "character": null
  }
}

PUT /user

Update an existing Foundry user

Updates fields on an existing user. Identify the user by id or name, then pass the fields to update in the data object. Cannot demote the last GM user. This is a GM-only operation.

Required scope: user:write

Parameters

Name	Type	Required	Source	Description
data	object	✓	body	Object containing user fields to update (name, role, password, color, avatar, character)
clientId	string		query	Client ID for the Foundry world
id	string		body, query	ID of the user to update
name	string		body, query	Name of the user to update (alternative to id)
userId	string		query, body	Foundry user ID or username to scope permissions (omit for GM-level access)

Returns

object - The updated user object

Try It Out

Code Examples

JavaScript
cURL
Python
TypeScript
Emojicode

const baseUrl = 'http://localhost:3010';
const path = '/user';
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({
      "id": "7odiSNcQcQ6jG68g",
      "data": {
        "role": 2
      }
    })
});
const data = await response.json();
console.log(data);

curl -X PUT 'http://localhost:3010/user?clientId=fvtt_099ad17ea199e7e3' \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"id":"7odiSNcQcQ6jG68g","data":{"role":2}}'

import requests

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

response = requests.put(
    url,
    params=params,
    headers={
        'x-api-key': 'your-api-key-here'
    },
    json={
      "id": "7odiSNcQcQ6jG68g",
      "data": {
        "role": 2
      }
    }
)
data = response.json()
print(data)

import axios from 'axios';

(async () => {
  const baseUrl = 'http://localhost:3010';
  const path = '/user';
  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: {
        "id": "7odiSNcQcQ6jG68g",
        "data": {
          "role": 2
        }
      }
  });
  const data = response.data;
  console.log(data);
})();

📦 sockets 🏠

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

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

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

  💭 Request body
  🔤{"id":"7odiSNcQcQ6jG68g","data":{"role":2}}🔤 ➡️ body

  💭 Build HTTP request
  🔤PUT /user🧲queryString🧲 HTTP/1.1❌r❌nHost: localhost:3010❌r❌nx-api-key: your-api-key-here❌r❌nContent-Type: application/json❌r❌nContent-Length: 43❌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-user-result",
  "requestId": "update-user_1778896442218",
  "data": {
    "id": "7odiSNcQcQ6jG68g",
    "name": "test-api-user",
    "role": 2,
    "isGM": false,
    "active": false,
    "color": "#28cc4c",
    "avatar": "icons/svg/mystery-man.svg",
    "character": null
  }
}

DELETE /user

Delete a Foundry user

Permanently deletes a user from the Foundry VTT world. Cannot delete yourself or the last GM user. This is a GM-only operation.

Required scope: user:write

Parameters

Name	Type	Source	Description
clientId	string	query	Client ID for the Foundry world
id	string	query	ID of the user to delete
name	string	query	Name of the user to delete (alternative to id)
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 = '/user';
const params = {
  clientId: 'fvtt_099ad17ea199e7e3',
  id: '7odiSNcQcQ6jG68g'
};
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/user?clientId=fvtt_099ad17ea199e7e3&id=7odiSNcQcQ6jG68g' \
  -H "x-api-key: your-api-key-here"

import requests

base_url = 'http://localhost:3010'
path = '/user'
params = {
    'clientId': 'fvtt_099ad17ea199e7e3',
    'id': '7odiSNcQcQ6jG68g'
}
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 = '/user';
  const params = {
    clientId: 'fvtt_099ad17ea199e7e3',
    id: '7odiSNcQcQ6jG68g'
  };
  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
  🔤/user🔤 ➡️ path

  💭 Query parameters
  🔤clientId=fvtt_099ad17ea199e7e3🔤 ➡️ clientId
  🔤id=7odiSNcQcQ6jG68g🔤 ➡️ id
  🔤?🧲clientId🧲&🧲id🧲🔤 ➡️ queryString

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

GET /users​

Parameters​

Returns​

Try It Out​

Code Examples​

Response​

GET /user​

Parameters​

Returns​

Try It Out​

Code Examples​

Response​

POST /user​

Parameters​

Returns​

Try It Out​

Code Examples​

Response​

PUT /user​

Parameters​

Returns​

Try It Out​

Code Examples​

Response​

DELETE /user​

Parameters​

Returns​

Try It Out​

Code Examples​

Response​

GET /users

Parameters

Returns

Try It Out

Code Examples

Response

GET /user

Parameters

Returns

Try It Out

Code Examples

Response

POST /user

Parameters

Returns

Try It Out

Code Examples

Response

PUT /user

Parameters

Returns

Try It Out

Code Examples

Response

DELETE /user

Parameters

Returns

Try It Out

Code Examples

Response