HTTP REST API

Exaplay 3 exposes an HTTP REST API for programmatic control of compositions, Playlists, Timelines, and media playback. This is the same API used by the Exaplay web UI and is suitable for integration with external show control systems, custom applications, and automation scripts.

Naming note: The Exaplay UI calls this composition type a Playlist. The wire protocol still uses the original cuelist identifier (composition type string, request names such as cuelist.seek, status fields such as CUEINDEX). This is intentional so existing integrations continue to work — treat cuelist and CueList in the protocol as synonyms for Playlist in the UI.

Connection

Parameter	Value
Protocol	HTTP
Default Port	8123
Content-Type	application/json

All commands are sent as POST requests to http://<host>:8123/project with a JSON body. The req field in the body specifies the command.

---

Composition Transport

These commands control playback of any composition (CueList or Timeline).

req value	Required fields	Description
composition.play	src-uid	Start playback
composition.pause	src-uid	Pause playback
composition.stop	src-uid	Stop playback
composition.set-time	src-uid, time	Seek to position (seconds)
composition.next	src-uid	Advance to the next cue/item
composition.prev	src-uid	Go back to the previous cue/item

Example: Seek a composition to 30 seconds

POST /project HTTP/1.1
Content-Type: application/json

{
  "req": "composition.set-time",
  "src-uid": 12345678,
  "time": 30.0
}

Response: 200 OK

---

CueList Commands

Seek within a CueList

Seek the currently playing item in a CueList to a specific time position. Unlike the generic composition.set-time endpoint, this endpoint validates that the target composition is a CueList and returns 400 Bad Request if it is not. Use this endpoint when integrating external control systems that specifically target CueList compositions.

For seeking any composition type (CueList or Timeline), use composition.set-time instead.

req value	Required fields	Description
cuelist.seek	src-uid, time	Seek CueList playback to position (seconds)

Fields:

Field	Type	Description
src-uid	integer	The UID of the CueList composition
time	float	Target position in seconds

Example: Seek a CueList to 15.5 seconds

POST /project HTTP/1.1
Content-Type: application/json

{
  "req": "cuelist.seek",
  "src-uid": 12345678,
  "time": 15.5
}

Response: 200 OK

---

Media Commands

Seek a specific media item

Seek within a specific media item by its UID. This is useful when you know the exact media item (e.g., from a CueList item click).

req value	Required fields	Description
media.set-time	src-uid, time	Seek a media item to position (seconds)

Fields:

Field	Type	Description
src-uid	integer	The UID of the media item
time	float	Target position in seconds

Example: Seek a media item to 10 seconds

POST /project HTTP/1.1
Content-Type: application/json

{
  "req": "media.set-time",
  "src-uid": 87654321,
  "time": 10.0
}

Response: 200 OK

---

Error Responses

HTTP Status	Meaning
200	Success
400	Bad request (missing or invalid parameters)
404	Composition or media item not found
500	Internal server error

---

Cross-Reference: Other Protocols

The same seeking functionality is available via other protocols:

Protocol	Command	Documentation
TCP	set:cuetime,COMPID,SECONDS	TCP API
UDP	set:cuetime,COMPID,SECONDS	UDP API
OSC	/exaplay/<comp>/cuetime <seconds>	Config → Network → OSC

---

Examples

Python

import requests

HOST = "http://192.168.1.5:8123"

# Seek a cuelist to 30 seconds
requests.post(f"{HOST}/project", json={
    "req": "cuelist.seek",
    "src-uid": 12345678,
    "time": 30.0,
})

# Play a composition
requests.post(f"{HOST}/project", json={
    "req": "composition.play",
    "src-uid": 12345678,
})

# Stop a composition
requests.post(f"{HOST}/project", json={
    "req": "composition.stop",
    "src-uid": 12345678,
})

JavaScript / Node.js

const HOST = "http://192.168.1.5:8123";

// Seek a cuelist to 15 seconds
await fetch(`${HOST}/project`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    req: "cuelist.seek",
    "src-uid": 12345678,
    time: 15.0,
  }),
});

curl

# Seek a cuelist to 45.5 seconds
curl -X POST http://192.168.1.5:8123/project \
  -H "Content-Type: application/json" \
  -d '{"req":"cuelist.seek","src-uid":12345678,"time":45.5}'

# Play a composition
curl -X POST http://192.168.1.5:8123/project \
  -H "Content-Type: application/json" \
  -d '{"req":"composition.play","src-uid":12345678}'