Foundry REST API

Join the discord server for updates, questions, and discussions

This project consists of two main components:

• Relay Server: A WebSocket server that facilitates communication between Foundry VTT and external applications.
• Foundry Module: A Foundry VTT module that connects to the relay server and provides access to Foundry data through a REST API.

Foundry REST API Relay Server

The server provides WebSocket connectivity and a REST API to access Foundry VTT data remotely.

Features

• Documentation
• WebSocket relay to connect Foundry clients with external applications
• REST API endpoints for searching Foundry content and retrieving entity data
• Client management for tracking Foundry connections
• Data storage and search results
• Roadmap

Installation

Using Docker Compose (Recommended)

The easiest way to run the relay server is using Docker Compose:

# Clone the repository
git clone https://github.com/ThreeHats/foundryvtt-rest-api-relay.git
cd foundryvtt-rest-api-relay

# Start the server
docker-compose up -d

# To stop the server
docker-compose down

The server will be available at http://localhost:3010 and will automatically restart unless manually stopped.

Manual Installation

### Install dependencies
pnpm install

### Run in development mode
PORT=3010 pnpm dev

### Build for production
pnpm build

### Start production server
pnpm local

Foundry REST API Module

A Foundry VTT module that connects to the relay server and provides access to Foundry data.

Features

• WebSocket connection to relay server
• Integration with Foundry's QuickInsert for powerful search capabilities
• Entity retrieval by UUID
• Configurable WebSocket relay URL and token

Installation

1. Install the module with the latest manifest link https://github.com/ThreeHats/foundryvtt-rest-api/releases/latest/download/module.json
2. Configure the WebSocket relay URL in module settings
3. Set your relay token (defaults to your world ID)

Configuration

After installing the module, go to the module settings to configure:

• WebSocket Relay URL - URL for the WebSocket relay server (default: ws://localhost:3010)
• WebSocket Relay Token - Token for grouping users together (default: your world ID)

Technical Details

Server Architecture

• Express.js - HTTP server framework
• WebSocket - For real-time communication
• Data Store - In-memory storage for entities and search results
• Client Manager - Handles client connections and message routing

Module Architecture

• Built with TypeScript for Foundry VTT
• Integrates with Foundry's QuickInsert for powerful search capabilities
• Provides WebSocket relay functionality for external applications