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

const baseUrl = 'http://localhost:3011';
const path = '/macros';
const params = {
  clientId: 'qsl-integration-test'
};
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

curl -X GET 'http://localhost:3011/macros?clientId=qsl-integration-test' \
  -H "x-api-key: your-api-key-here"

Python

import requests

base_url = 'http://localhost:3011'
path = '/macros'
params = {
    'clientId': 'qsl-integration-test'
}
url = f'{base_url}{path}'

response = requests.get(
    url,
    params=params,
    headers={
        'x-api-key': 'your-api-key-here'
    }
)
data = response.json()
print(data)

TypeScript

import axios from 'axios';

(async () => {
  const baseUrl = 'http://localhost:3011';
  const path = '/macros';
  const params = {
    clientId: 'qsl-integration-test'
  };
  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);
})();

Emojicode

📦 sockets 🏠

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

🏁 🍇
  💭 Connection settings
  🔤localhost🔤 ➡️ host
  3011 ➡️ port
  🔤/macros🔤 ➡️ path

  💭 Query parameters
  🔤clientId=qsl-integration-test🔤 ➡️ clientId
  🔤?🧲clientId🧲🔤 ➡️ queryString

  💭 Build HTTP request
  🔤GET /macros🧲queryString🧲 HTTP/1.1❌r❌nHost: localhost:3011❌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_1782956928928",
  "macros": [
    0: {
      "uuid": "Macro.7zDXWfoXIJPrJ7uh",
      "id": "7zDXWfoXIJPrJ7uh",
      "name": "test-macro",
      "type": "script",
      "author": "Gamemaster",
      "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

const baseUrl = 'http://localhost:3011';
const path = '/macro/Macro.7zDXWfoXIJPrJ7uh/execute';
const params = {
  clientId: 'qsl-integration-test'
};
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

curl -X POST 'http://localhost:3011/macro/Macro.7zDXWfoXIJPrJ7uh/execute?clientId=qsl-integration-test' \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"args":{"targetName":"Goblin","damage":100000,"effect":"poison"}}'

Python

import requests

base_url = 'http://localhost:3011'
path = '/macro/Macro.7zDXWfoXIJPrJ7uh/execute'
params = {
    'clientId': 'qsl-integration-test'
}
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)

TypeScript

import axios from 'axios';

(async () => {
  const baseUrl = 'http://localhost:3011';
  const path = '/macro/Macro.7zDXWfoXIJPrJ7uh/execute';
  const params = {
    clientId: 'qsl-integration-test'
  };
  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);
})();

Emojicode

📦 sockets 🏠

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

🏁 🍇
  💭 Connection settings
  🔤localhost🔤 ➡️ host
  3011 ➡️ port
  🔤/macro/Macro.7zDXWfoXIJPrJ7uh/execute🔤 ➡️ path

  💭 Query parameters
  🔤clientId=qsl-integration-test🔤 ➡️ clientId
  🔤?🧲clientId🧲🔤 ➡️ queryString

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

  💭 Build HTTP request
  🔤POST /macro/Macro.7zDXWfoXIJPrJ7uh/execute🧲queryString🧲 HTTP/1.1❌r❌nHost: localhost:3011❌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_1782956928931",
  "uuid": "Macro.7zDXWfoXIJPrJ7uh",
  "success": true,
  "result": {
    "success": true,
    "damageDealt": 100000,
    "target": "Goblin"
  }
}