Skip to main content

FoundryVTT REST API Reference

This is the API reference for the FoundryVTT REST API Relay server.

Available Endpoints​

The API is divided into several resource groups:

  • Auth - Registration, login, API key and connection token management
  • Canvas - Manipulate canvas embedded documents (tokens, walls, lights, etc.)
  • Chat - Send, retrieve, and subscribe to chat messages (includes SSE streaming)
  • Clients - List connected Foundry VTT worlds
  • DnD5e - D&D 5th Edition specific endpoints
  • Effects - Read and manage active effects on actors and tokens
  • Encounter - Combat encounter management
  • Entity - General entity manipulation (actors, items, etc.)
  • Events - Subscribe to real-time Foundry hook events via SSE
  • File System - File management operations
  • Macro - Execute and manage macros
  • Playlist - Control playlists and audio tracks
  • Roll - Perform dice rolls and subscribe to roll events (includes SSE streaming)
  • Scene - Create, update, delete, and switch scenes
  • Search - Search the Foundry database
  • Session - Manage headless Foundry sessions
  • Sheet - Interact with character sheets
  • Structure - Get information about world structure
  • User - List and manage Foundry VTT users
  • Utility - Miscellaneous utility endpoints
  • WebSocket - Bidirectional real-time communication via WebSocket

Each endpoint is documented with its path, HTTP method, required and optional parameters, and expected response format.

Real-Time Streaming (SSE)​

Some endpoints support Server-Sent Events (SSE) for real-time streaming:

  • GET /chat/subscribe - Stream chat messages as they are created, updated, or deleted
  • GET /rolls/subscribe - Stream dice roll events as they occur
  • GET /hooks/subscribe - Stream Foundry hook events (combat, actor, scene, and more)

These endpoints return a persistent text/event-stream connection. See the individual endpoint documentation for code examples in JavaScript, TypeScript, Python, and cURL.

Authentication​

Most API endpoints require authentication with an API key. Provide your API key in the x-api-key header with each request.