> How to use REST API to control SPX Graphics Controller?
SPX Graphics Controller provides a REST API for programmatic control. The API allows external devices and software to control [[Documentation/Graphics Controller/Rundown Settings|rundowns]], items, and playout.
The API is available at:
```text
http://localhost:5656/api/v1
```
Visit this URL in your browser to see up-to-date API documentation and available endpoints.
---
## API versions
There are 3 groups of of available APIs:
1. [[Documentation/Control Interfaces/REST/Common api|Common API]]
2. [[Documentation/Control Interfaces/REST/Control api|Control API]]
3. [[Documentation/Control Interfaces/REST/Server api|Server API]]
There groups of APIs are available in [[Documentation/Products/Overview|different versions of SPX GC]] and each are unique to handle different workflows
The updated API docs are built into each version of SPX and can be accessed from the main menu or `/api/v1`
![[Pasted image 20251209124944.png|200]]
> [!info]
> All API endpoints are compatible for SPX and OGraf formats.
### 🟢[[Documentation/Control Interfaces/REST/Common api|Common API]]
This is a set of utility APIs. Things like `panic` endpoint for force clearing graphics and `feedproxy` to resolve CORS issues.
> [!info] Available for all versions of SPX GC
### 🟠[[Documentation/Control Interfaces/REST/Control api|Control API]]
This is for controlling the SPX GC Interface with API commands. This is useful for manual operation workflows and enables external control devices (ie. Streamdeck) to communicate with the GC user interface.
> [!info] Available in SPX Production and SPX Broadcast
### 🔵[[Documentation/Control Interfaces/REST/Server api|Server API]]
This is for a fully automated graphics workflow where the playout commands are sent directly to the SPX server. This is a crucial set of APIs to integrate with playout systems for broadcast (ie. Viz Mosart, Dalet Pyramid, etc.).
This also includes APIs for [[Rundown Settings|rundown management]] with the ability to read and update rundowns.
> [!info] Available in SPX Broadcast
## Examples
### Play Current Item
```bash
curl -X POST http://localhost:5656/api/v1/rundown/play
```
### Get Rundown Status
```bash
curl http://localhost:5656/api/v1/rundown/status
```
### Load Rundown
```bash
curl -X POST http://localhost:5656/api/v1/rundown/load \
-H "Content-Type: application/json" \
-d '{"project": "My Project", "rundown": "My Rundown"}'
```
## Interactive Documentation
The best way to explore the API is through the interactive documentation:
1. Start SPX server
2. Open browser to `http://localhost:5656/api/v1`
3. Browse available endpoints
4. Test API calls directly
## API key
SPX v.1.1.4 introduced support for API key. The key can be any "secret string" and it must be manually added to the [[Documentation/Server/Configurations|config.json]] file. An example:
```json
// config.general
"apikey": "MyVerySecretKey"
```
By default the config has an empty string as the value which means "no restrictions", any computer in the network can send API commands to SPX. If the config has any value in the "apikey" setting, this same key must be passed as an URL parameter. An example:
```text
// API call with the key added
http://localhost:5656/api/v1/panic?apikey=MyVerySecretKey
```
## Hardware controllers
![[Pasted image 20260128115537.png]]SPX API is useful for example with a Stream Deck or similar physical device. You can create buttons for several things such as
- Loading a named project and rundown
- Navigating up/down the rundown
- Playing/stopping selected items
- Playing/stopping items by ID
- Modifying graphics live while on-screen
- And more...
Also additional software can be created to control SPX graphics by utilizing these API capabilities. These small software controllers or custom user-interfaces are called **SPX [[Documentation/Graphics Controller/Plugins & Extensions|Extensions]]**.
An example extension project for developers
You can [download a zip file](https://storage.googleapis.com/spx-gc-bucket-fi/CommunityFiles/ExampleExtensionForDevelopers.zip) that contains an **example extension** and **a [[Documentation/Graphic Templates/Overview|template]]** as shown in the below GIF animation. The package has subfolders for templates and plugins so please unzip these to their corresponding folders within the SPX installation folder.
The extension can
- **play** the graphic into the SPX [[Documentation/Renderer/Overview|renderer]]
- **increment** a number on-screen
- **stop** the template
You can see and modify HTML and Javascript code in both the extension and the template and learn the core functionalities and concepts in developing custom user interfaces for graphics-related workflows, such as game show controllers or similar non-linear productions.
![[Pasted image 20260128115602.png]]![[PPibdtuhG2.gif]]
The template comes with two custom functions that can be triggered externally with the help of the SPX control API.
<span style="font-size: 1.25em;">setValue()</span>
Set the number value directly. If the given parameter is not a number it will be interpreted as zero (0). The below example sets the value to 50.
```text
// Note: default host:port
http://localhost:5656/api/v1/invokeTemplateFunction?webplayout=6&function=setValue¶ms=50
```
<span style="font-size: 1.25em;">changeValue()</span>
Modify current value. The parameter can be positive (such as 1) or negative (such as -1). The below increments the value by 10.
```text
// Note: default host:port
http://localhost:5656/api/v1/invokeTemplateFunction?webplayout=6&function=changeValue¶ms=10
```
These URL's can for example be added to the Stream Deck and counters can be incremented or decremented with dedicated hardware buttons.
## JSON data
A single value is straightforward to pass as a basic string parameter.
Larger collection of values can be sent to the template function by utilizing **JSON.stringify()** and **encodeURI()** functions in the extension when sending data to the template via the SPX server's invokeTemplateFunction API endpoint.
The data in the template can be converted back to a JSON object with **decodeURI()** and **JSON.parse()** functions for further processing.
Example:
```json
// Original JSON object
var personInfo = {
name: "John Doe",
age: 32,
kids: ["Emma", "Sam"]
}
```
Converted to a string with JSON.stringify() and encodeURI()
```text
'%7B%22name%22:%22John%20Doe%22,%22age%22:32,%22kids%22:%5B%22Emma%22,%22Sam%22%5D%7D'
```
## Executing functions in SPX Extensions over the API
SPX version 1.3.0 introduced **invokeExtensionFunction** API-endpoint which uses SPX's internal messaging system to pass commands from API to server and onwards to extensions. This requires the HTML/HEAD of the extension to have the following properties linked from the SPX server:
```html
<script src="/js/socket.io.js"></script>
<script>var socket = io();</script>
<script src="/js/spx_gc.js"></script>
```
With this mechanism extensions can be controlled externally (such as using the Stream Deck). The example extension above has a function **sendCmd** and with parameter **increment** it will increment the number on screen. This can be executed with the following API endpoint:
```text
http://localhost:5656/api/v1/invokeExtensionFunction?function=sendCmd¶ms=incrementNumber
```
A larger collection of values can be sent to the function by utilizing JSON.stringify() and encodeURI() methods to stringify JSON data, see above.
---
## Read Next
- [[Documentation/Control Interfaces/REST/Common api|Common API]] - Utility endpoints for all SPX versions
- [[Documentation/Control Interfaces/REST/Control api|Control API]] - UI control endpoints
- [[Documentation/Control Interfaces/REST/Server api|Server API]] - Automation endpoints
- [[Documentation/Control Interfaces/External Control|External Control]] - Hardware controller integration