Skip to content

README.md

Latest commit

 

History

History
97 lines (64 loc) · 3.64 KB

README.md

File metadata and controls

97 lines (64 loc) · 3.64 KB

Foundry REST API Module

The Foundry VTT companion module for the Foundry REST API — connects your Foundry world to a relay server, enabling external tools and automations to interact with your game.

Discord License: MIT

What Is This?

This module bridges your Foundry VTT world to a relay server via WebSocket, allowing external applications to read and modify your world data through a REST API.

┌─────────────────┐      WebSocket       ┌─────────────────┐      REST API      ┌─────────────────┐
│   Foundry VTT   │ ◄──────────────────► │  Relay Server   │ ◄────────────────► │  Your App/Tool  │
│   + This Module │                      │                 │                    │                 │
└─────────────────┘                      └─────────────────┘                    └─────────────────┘

Use cases: Custom dashboards, MIDI controller integration, Discord bots, Stream Deck triggers, automated testing, and more.

Quick Start

1. Install the Module

Add this manifest URL in Foundry VTT (Settings → Add-on Modules → Install Module):

https://github.com/ThreeHats/foundryvtt-rest-api/releases/latest/download/module.json

2. Get an API Key

Option A: Public Relay (Easiest)
Go to https://foundryrestapi.com, create an account, and copy your API key.

Option B: Self-Host
See the relay server documentation to run your own instance.

3. Configure the Module

Enable the module in your world, then go to Module Settings and enter:

  • Your API Key
  • The WebSocket Relay URL (default: wss://foundryrestapi.com/)

4. Start Making API Calls

# List connected worlds
curl -X GET "https://foundryrestapi.com/clients" \
  -H "x-api-key: YOUR_API_KEY"

Module Settings

Setting Default Description
WebSocket Relay URL wss://foundryrestapi.com/ Relay server WebSocket endpoint
API Key — Your API key from the relay server
Log Level info Controls module log verbosity (debug, info, warn, error)
Ping Interval 30 seconds Keep-alive ping frequency
Max Reconnect Attempts 20 Reconnection attempts on disconnect
Reconnect Base Delay 1000 ms Initial delay before reconnecting (exponential backoff)

Project Ecosystem

Component Description
This Module Foundry VTT module (you are here)
Relay Server Node.js server with REST API and WebSocket relay

Tech Stack

  • TypeScript module for Foundry VTT
  • WebSocket communication with automatic reconnection

Links

License

MIT © ThreeHats