Structure

GET /structure

Get the structure of the Foundry world

Retrieves the folder and compendium structure for the specified Foundry world.

Required scope: structure:read

Parameters

Name	Type	Source	Description
clientId	string	query	Client ID for the Foundry world
includeEntityData	boolean	query	Whether to include full entity data or just UUIDs and names
path	string	query	Path to read structure from (null = root)
recursive	boolean	query	Whether to read down the folder tree
recursiveDepth	number	query	Depth to recurse into folders (default 5)
types	string	query	Types to return (Scene/Actor/Item/JournalEntry/RollTable/Cards/Macro/Playlist), can be comma-separated or JSON array
userId	string	query, body	Foundry user ID or username to scope permissions (omit for GM-level access)

Returns

object - The folder and compendium structure

Try It Out

Code Examples

JavaScript
cURL
Python
TypeScript
Emojicode

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

import requests

base_url = 'http://localhost:3010'
path = '/structure'
params = {
    'clientId': 'fvtt_099ad17ea199e7e3',
    'includeEntityData': 'true',
    'recursive': 'true',
    'types': 'Scene'
}
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 = '/structure';
  const params = {
    clientId: 'fvtt_099ad17ea199e7e3',
    includeEntityData: 'true',
    recursive: 'true',
    types: 'Scene'
  };
  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
  🔤/structure🔤 ➡️ path

  💭 Query parameters
  🔤clientId=fvtt_099ad17ea199e7e3🔤 ➡️ clientId
  🔤includeEntityData=true🔤 ➡️ includeEntityData
  🔤recursive=true🔤 ➡️ recursive
  🔤types=Scene🔤 ➡️ types
  🔤?🧲clientId🧲&🧲includeEntityData🧲&🧲recursive🧲&🧲types🧲🔤 ➡️ queryString

  💭 Build HTTP request
  🔤GET /structure🧲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": "structure-result",
  "requestId": "structure_1778896423682",
  "data": {
    "folders": {
      "test-folder": { 3 keys }
    },
    "entities": {
      "scenes": [ 20 items ]
    }
  }
}

GET /get-folder

Get a specific folder by name

Required scope: structure:read

Parameters

Name	Type	Required	Source	Description
name	string	✓	body, query	Name of the folder to retrieve
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 folder information and its contents

Try It Out

Code Examples

JavaScript
cURL
Python
TypeScript
Emojicode

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

import requests

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

  💭 Query parameters
  🔤clientId=fvtt_099ad17ea199e7e3🔤 ➡️ clientId
  🔤name=test-folder🔤 ➡️ name
  🔤?🧲clientId🧲&🧲name🧲🔤 ➡️ queryString

  💭 Build HTTP request
  🔤GET /get-folder🧲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-folder-result",
  "requestId": "get-folder_1778896423713",
  "data": {
    "id": "qVncHkNOxAuctXy2",
    "uuid": "Folder.qVncHkNOxAuctXy2",
    "name": "test-folder",
    "type": "Scene",
    "parentFolder": null,
    "contents": []
  }
}

POST /create-folder

Create a new folder

Required scope: structure:write

Parameters

Name	Type	Required	Source	Description
name	string	✓	body, query	Name of the new folder
folderType	string	✓	body, query	Type of folder (Scene, Actor, Item, JournalEntry, RollTable, Cards, Macro, Playlist)
clientId	string		query	Client ID for the Foundry world
parentFolderId	string		body, query	ID of the parent folder (optional for root level)
userId	string		query, body	Foundry user ID or username to scope permissions (omit for GM-level access)

Returns

object - The created folder information

Try It Out

Code Examples

JavaScript
cURL
Python
TypeScript
Emojicode

const baseUrl = 'http://localhost:3010';
const path = '/create-folder';
const params = {
  clientId: 'fvtt_099ad17ea199e7e3',
  name: 'test-folder',
  folderType: 'Scene'
};
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'
  }
});
const data = await response.json();
console.log(data);

curl -X POST 'http://localhost:3010/create-folder?clientId=fvtt_099ad17ea199e7e3&name=test-folder&folderType=Scene' \
  -H "x-api-key: your-api-key-here"

import requests

base_url = 'http://localhost:3010'
path = '/create-folder'
params = {
    'clientId': 'fvtt_099ad17ea199e7e3',
    'name': 'test-folder',
    'folderType': 'Scene'
}
url = f'{base_url}{path}'

response = requests.post(
    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 = '/create-folder';
  const params = {
    clientId: 'fvtt_099ad17ea199e7e3',
    name: 'test-folder',
    folderType: 'Scene'
  };
  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'
    },
    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
  🔤/create-folder🔤 ➡️ path

  💭 Query parameters
  🔤clientId=fvtt_099ad17ea199e7e3🔤 ➡️ clientId
  🔤name=test-folder🔤 ➡️ name
  🔤folderType=Scene🔤 ➡️ folderType
  🔤?🧲clientId🧲&🧲name🧲&🧲folderType🧲🔤 ➡️ queryString

  💭 Build HTTP request
  🔤POST /create-folder🧲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": "create-folder-result",
  "requestId": "create-folder_1778896423673",
  "data": {
    "id": "qVncHkNOxAuctXy2",
    "uuid": "Folder.qVncHkNOxAuctXy2",
    "name": "test-folder",
    "type": "Scene",
    "parentFolder": null
  }
}

DELETE /delete-folder

Delete a folder

Required scope: structure:write

Parameters

Name	Type	Required	Source	Description
folderId	string	✓	body, query	ID of the folder to delete
clientId	string		query	Client ID for the Foundry world
deleteAll	boolean		body, query	Whether to delete all entities in the folder
userId	string		query, body	Foundry user ID or username to scope permissions (omit for GM-level access)

Returns

object - Confirmation of deletion

Try It Out

Code Examples

JavaScript
cURL
Python
TypeScript
Emojicode

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

import requests

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

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

  💭 Build HTTP request
  🔤DELETE /delete-folder🧲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-folder-result",
  "requestId": "delete-folder_1778896423715",
  "data": {
    "deleted": true,
    "folderId": "qVncHkNOxAuctXy2",
    "entitiesDeleted": 0,
    "foldersDeleted": 1
  }
}

GET /contents/:path

This route is deprecated

Use /structure with the path query parameter instead.

Required scope: structure:read

Returns

object - Error message directing to use /structure endpoint

GET /structure​

Parameters​

Returns​

Try It Out​

Code Examples​

Response​

GET /get-folder​

Parameters​

Returns​

Try It Out​

Code Examples​

Response​

POST /create-folder​

Parameters​

Returns​

Try It Out​

Code Examples​

Response​

DELETE /delete-folder​

Parameters​

Returns​

Try It Out​

Code Examples​

Response​

GET /contents/:path​

Returns​

Try It Out​

GET /structure

Parameters

Returns

Try It Out

Code Examples

Response

GET /get-folder

Parameters

Returns

Try It Out

Code Examples

Response

POST /create-folder

Parameters

Returns

Try It Out

Code Examples

Response

DELETE /delete-folder

Parameters

Returns

Try It Out

Code Examples

Response

GET /contents/:path

Returns

Try It Out