Skip to main content

REST API

Control FXCanvas from Stream Deck Companion, web applications, and any HTTP-capable software using a simple REST API. Perfect for creating custom control surfaces, automation scripts, and show control integrations.

Remote Control settings showing REST API server configuration

What is the REST API?​

The REST API provides HTTP endpoints for controlling FXCanvas. Unlike OSC which uses UDP messages, the REST API uses standard HTTP requests with JSON responses, making it easy to integrate with:

  • Bitfocus Companion — Stream Deck control software
  • Web applications — Custom browser-based controllers
  • Automation scripts — Python, Node.js, or any language with HTTP support
  • Show control systems — QLab, Isadora, and similar software

For the full list of endpoints, request/response schemas, and example payloads, see the REST API Reference.

Getting Started​

Enabling the REST API​

  1. Open Edit → Settings from the menu bar
  2. Select the Remote Control tab in the sidebar
  3. Check Enable REST API Server
  4. The default port is 8080 — change if needed
  5. Click Apply if you changed the port

When enabled, the status section shows:

StatusDescription
Server Running (green)Ready to receive HTTP requests
Server Starting... (yellow)Service is initializing
Server Disabled (gray)REST API is turned off

REST API server status showing Server Running with address and quick actions

Testing Your Connection​

The quickest way to test:

  1. Enable the REST API in Settings
  2. Click Open in Browser in the Quick Actions section
  3. You should see a JSON response with server status

Or use curl from a terminal:

curl http://localhost:8080/api/v1/status

Interactive Documentation​

When the REST API is running, interactive docs are available at:

  • http://localhost:8080/api/v1/docs — Browse and test all endpoints in your browser
  • http://localhost:8080/api/v1/openapi.yaml — OpenAPI 3.0 spec (importable into Postman, Insomnia, etc.)

You can also click the API Docs button in Settings → Remote Control.

Stream Deck Companion Setup​

The REST API is designed for easy integration with Bitfocus Companion.

Basic Setup​

  1. In Companion, add a Generic HTTP connection
  2. Set the Base URL to your computer's IP and port (e.g., http://192.168.1.100:8080)
  3. Create buttons using the endpoints from the API Reference

Example Button Configurations​

Next Palette Button:

  • Method: POST
  • Path: /api/v1/palettes/next
  • Body: (empty)

Select Specific Source:

  • Method: POST
  • Path: /api/v1/sources/select
  • Body: {"name": "Plasma"}

Blackout Toggle:

  • Method: POST
  • Path: /api/v1/global/blackout
  • Body: {"enabled": true}

Master Dimmer (with variable):

  • Method: POST
  • Path: /api/v1/global/dimmer
  • Body: {"value": $(internal:custom_dimmer)}

Thumbnail for button image:

  • Method: GET
  • Path: /api/v1/thumbnails/current?size=72
  • Use as button image (returns PNG)

Authentication​

Authentication is optional. Enable it in Settings → Remote Control if you want to restrict access.

When enabled, include your API key with every request:

  • Header: X-API-Key: your-key-here
  • Or: Authorization: Bearer your-key-here

The /status, /docs, and /openapi.yaml endpoints are always accessible without authentication.

Name Matching​

When selecting items by name, the API uses flexible matching:

  • Case-insensitive: "ocean blues" matches "Ocean Blues"
  • Underscore tolerance: "ocean_blues" matches "Ocean Blues"
  • Hyphen tolerance: "ocean-blues" matches "Ocean Blues"

This makes it easy to use names in URLs and scripts without worrying about exact formatting.

Settings Configuration​

Access REST API configuration via Edit → Settings → Remote Control tab.

SettingDescription
Enable REST API ServerTurns the HTTP server on or off
PortTCP port FXCanvas listens on (default: 8080, range: 1024–65535)
API KeyOptional authentication key
StatusShows current server state
Network AddressURL for accessing from other devices

Quick Actions​

  • Open in Browser — Opens the status endpoint in your default browser
  • API Docs — Opens the interactive API documentation
  • Copy Base URL — Copies the server URL to clipboard

Troubleshooting​

Server Not Starting​

  • Another application may be using port 8080 — try a different port
  • Check the Log Viewer for error messages

Requests Not Working​

  1. Is the REST API enabled in Settings?
  2. Is the server status showing "Running"?
  3. Are you using the correct IP address and port?
  4. Is your firewall allowing connections on the configured port?

CORS Issues (Web Applications)​

The REST API includes CORS headers allowing requests from any origin. If you're encountering CORS errors, ensure you're making requests to the correct URL and that the server is running.

Item Not Found​

  • Use the list endpoint (e.g., GET /api/v1/palettes) to see available items
  • Names are case-insensitive and tolerate underscores/hyphens
  • Try selecting by index instead