Macro

GET /macros

Get all macros

Retrieves a list of all macros available in the Foundry world.

Required scope: macro:list

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 - An array of macros with details

Try It Out

Code Examples

JavaScript
cURL
Python
TypeScript
Emojicode

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

import requests

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

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

  💭 Build HTTP request
  🔤GET /macros🧲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": "macros-result",
  "requestId": "macros_1778896436098",
  "macros": [
    0: {
      "uuid": "Macro.BZmzcTiPJm3brbfb",
      "id": "BZmzcTiPJm3brbfb",
      "name": "test-macro",
      "type": "script",
      "author": "tester",
      "command": "// Example macro that uses parameters
function myMacro(args) {
  const targetName = args.targetName || "Target";
  const damage = args.damage || 0;
  const effect = args.effect || "none";
  
  // Use the parameters
  console.log(`Attacking ${targetName} for ${damage} ${effect} damage`);
  
  // Return a value (can be any data type)
  return {
    success: true,
    damageDealt: damage,
    target: targetName
  };
}

// Don't forget to return the result of your function
return myMacro(args);",
      "img": "icons/svg/dice-target.svg",
      "scope": "global",
      "canExecute": true
    },
    1: {
      "uuid": "Macro.CruvJo43Zk2SK7Yl",
      "id": "CruvJo43Zk2SK7Yl",
      "name": "test-macro",
      "type": "script",
      "author": "tester",
      "command": "// Example macro that uses parameters
function myMacro(args) {
  const targetName = args.targetName || "Target";
  const damage = args.damage || 0;
  const effect = args.effect || "none";
  
  // Use the parameters
  console.log(`Attacking ${targetName} for ${damage} ${effect} damage`);
  
  // Return a value (can be any data type)
  return {
    success: true,
    damageDealt: damage,
    target: targetName
  };
}

// Don't forget to return the result of your function
return myMacro(args);",
      "img": "icons/svg/dice-target.svg",
      "scope": "global",
      "canExecute": true
    },
    2: {
      "uuid": "Macro.j7NHQIWtXA4AG8Jt",
      "id": "j7NHQIWtXA4AG8Jt",
      "name": "Nuke",
      "type": "script",
      "author": "Gamemaster",
      "command": "async function cleanSlate() {
    // List of document types to wipe
    const collections = [
        game.scenes,
        game.actors,
        game.items,
        game.journal,
        game.tables,
        game.playlists,
        game.cards,
        // game.macros // Uncomment this line if you want to delete all macros too
    ];

    for (let collection of collections) {
        const ids = collection.map(doc => doc.id);
        if (ids.length > 0) {
            console.log(`Deleting ${ids.length} documents from ${collection.name}...`);
            await collection.documentClass.deleteDocuments(ids);
        }
    }

    ui.notifications.info("World cleanup complete. A fresh start awaits!");
}

// Confirmation Dialog
new Dialog({
    title: "Nuclear Option: Clear World Data",
    content: `
        <div style="text-align: center;">
            <p><i class="fas fa-exclamation-triangle fa-3x" style="color: #ff6b6b;"></i></p>
            <p>This will <strong>permanently delete</strong> all Scenes, Actors, Items, Journals, and more.</p>
            <p><em>Are you absolutely sure?</em></p>
        </div>`,
    buttons: {
        confirm: {
            icon: '<i class="fas fa-trash"></i>',
            label: "Delete Everything",
            callback: () => cleanSlate()
        },
        cancel: {
            icon: '<i class="fas fa-times"></i>',
            label: "Cancel"
        }
    },
    default: "cancel"
}).render(true);",
      "img": "icons/svg/poison.svg",
      "scope": "global",
      "canExecute": true
    },
    3: {
      "uuid": "Macro.6HET3CG6IBNcRxCB",
      "id": "6HET3CG6IBNcRxCB",
      "name": "test-macro",
      "type": "script",
      "author": "tester",
      "command": "// Example macro that uses parameters
function myMacro(args) {
  const targetName = args.targetName || "Target";
  const damage = args.damage || 0;
  const effect = args.effect || "none";
  
  // Use the parameters
  console.log(`Attacking ${targetName} for ${damage} ${effect} damage`);
  
  // Return a value (can be any data type)
  return {
    success: true,
    damageDealt: damage,
    target: targetName
  };
}

// Don't forget to return the result of your function
return myMacro(args);",
      "img": "icons/svg/dice-target.svg",
      "scope": "global",
      "canExecute": true
    }
  ]
}

POST /macro/:uuid/execute

Execute a macro by UUID

Executes a specific macro in the Foundry world by its UUID.

Required scope: macro:execute

Parameters

Name	Type	Required	Source	Description
uuid	string	✓	params	UUID of the macro to execute
clientId	string		query	Client ID for the Foundry world
args	object		body	Optional arguments to pass to the macro execution
userId	string		query, body	Foundry user ID or username to scope permissions (omit for GM-level access)

Returns

object - Result of the macro execution

Try It Out

Code Examples

JavaScript
cURL
Python
TypeScript
Emojicode

const baseUrl = 'http://localhost:3010';
const path = '/macro/Macro.6HET3CG6IBNcRxCB/execute';
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({
      "args": {
        "targetName": "Goblin",
        "damage": 100000,
        "effect": "poison"
      }
    })
});
const data = await response.json();
console.log(data);

curl -X POST 'http://localhost:3010/macro/Macro.6HET3CG6IBNcRxCB/execute?clientId=fvtt_099ad17ea199e7e3' \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"args":{"targetName":"Goblin","damage":100000,"effect":"poison"}}'

import requests

base_url = 'http://localhost:3010'
path = '/macro/Macro.6HET3CG6IBNcRxCB/execute'
params = {
    'clientId': 'fvtt_099ad17ea199e7e3'
}
url = f'{base_url}{path}'

response = requests.post(
    url,
    params=params,
    headers={
        'x-api-key': 'your-api-key-here'
    },
    json={
      "args": {
        "targetName": "Goblin",
        "damage": 100000,
        "effect": "poison"
      }
    }
)
data = response.json()
print(data)

import axios from 'axios';

(async () => {
  const baseUrl = 'http://localhost:3010';
  const path = '/macro/Macro.6HET3CG6IBNcRxCB/execute';
  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: {
        "args": {
          "targetName": "Goblin",
          "damage": 100000,
          "effect": "poison"
        }
      }
  });
  const data = response.data;
  console.log(data);
})();

📦 sockets 🏠

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

🏁 🍇
  💭 Connection settings
  🔤localhost🔤 ➡️ host
  3010 ➡️ port
  🔤/macro/Macro.6HET3CG6IBNcRxCB/execute🔤 ➡️ path

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

  💭 Request body
  🔤{"args":{"targetName":"Goblin","damage":100000,"effect":"poison"}}🔤 ➡️ body

  💭 Build HTTP request
  🔤POST /macro/Macro.6HET3CG6IBNcRxCB/execute🧲queryString🧲 HTTP/1.1❌r❌nHost: localhost:3010❌r❌nx-api-key: your-api-key-here❌r❌nContent-Type: application/json❌r❌nContent-Length: 66❌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": "macro-execute-result",
  "requestId": "macro-execute_1778896436102",
  "uuid": "Macro.6HET3CG6IBNcRxCB",
  "success": true,
  "result": {
    "success": true,
    "damageDealt": 100000,
    "target": "Goblin"
  }
}

GET /macros​

Parameters​

Returns​

Try It Out​

Code Examples​

Response​

POST /macro/:uuid/execute​

Parameters​

Returns​

Try It Out​

Code Examples​

Response​

GET /macros

Parameters

Returns

Try It Out

Code Examples

Response

POST /macro/:uuid/execute

Parameters

Returns

Try It Out

Code Examples

Response