OrbixPlay API
Playlists, Slots & List Codes
OrbixPlay provides simple and secure REST APIs for subscribers to manage playlists, check slot usage, and work with list codes. All endpoints require your customer key in the x-customer-key header.
Authentication
Every request must include your subscriber customer key. Only subscriber accounts can use these APIs.
- Header: x-customer-key: <your-customer-key>
- Header: Content-Type: application/json
- Obtain your customer key from your OrbixPlay subscriber account or support team.
1. Add Playlist API
Adds a new playlist for a specific device.
Endpoint
POST https://apis.orbixplay.com/add-playlistHeaders
- Content-Type: application/json
- x-customer-key: <your-customer-key>
Request Body
{
"query": {
"deviceid": "<device-id>",
"playlistName": "<playlist-name>",
"username": "<username>",
"password": "<password>",
"host": "<host-url-or-code>",
"notes": "<optional-notes>"
}
}Fields
- deviceid: Unique identifier of the device (must exist in the database).
- playlistName: Playlist name.
- username: Username associated with the playlist.
- password: Password associated with the playlist.
- host (string or integer): if string, considered a URL; if integer, considered a host_code and will be added to the playlist document.
- notes (optional): Free-text notes stored on the playlist.
Response
- Success: 200 OK — playlist inserted (includes playlist_id)
- 400 — missing required fields or invalid host format
- 403 — subscription expired or slot limit reached
- 404 — device not found or customer key not found
- 500 — internal server error
2. Update Playlist API
Updates an existing playlist by playlist_id. Send only the fields you want to change (username, password, host, playlist name, notes, or deviceid).
Endpoint
POST https://apis.orbixplay.com/update-playlistHeaders
- Content-Type: application/json
- x-customer-key: <your-customer-key>
Request Body
{
"query": {
"playlist_id": "<playlist-id>",
"playlistName": "<optional-new-name>",
"username": "<optional-username>",
"password": "<optional-password>",
"host": "<optional-host-url-or-code>",
"notes": "<optional-notes>",
"deviceid": "<optional-device-id>"
}
}Fields
- playlist_id (required): Unique playlist ID returned by Add Playlist.
- playlistName (optional): New playlist name.
- username (optional): New username.
- password (optional): New password.
- host (optional): URL or numeric host_code.
- notes (optional): Free-text notes.
- deviceid (optional): Move the playlist to another existing device.
Response
- Success: 200 OK — returns updated playlist and used_slots
- 400 — missing playlist_id, invalid id, or no fields to update
- 403 — not allowed for this key or slot limit reached
- 404 — playlist, device, host code, or customer key not found
- 500 — internal server error
3. Delete Playlists API (all for device)
Deletes all playlists for the provided device.
Endpoint
POST https://apis.orbixplay.com/delete-playlistsHeaders
- Content-Type: application/json
- x-customer-key: <your-customer-key>
Request Body
{
"query": {
"deviceid": "<device-id>"
}
}Fields
- deviceid: Unique identifier of the device whose playlists should be deleted.
Response
- Success: 200 OK — playlists deleted
- 400 — missing required fields
- 403 — not allowed for this key
- 404 — device not found, no playlists to delete, or customer key not found
- 500 — internal server error
4. Delete Single Playlist API
Deletes one playlist identified by playlist_id, without removing other playlists on the device.
Endpoint
POST https://apis.orbixplay.com/delete-playlistHeaders
- Content-Type: application/json
- x-customer-key: <your-customer-key>
Request Body
{
"query": {
"playlist_id": "<playlist-id>"
}
}Fields
- playlist_id: Unique playlist ID to delete.
Response
- Success: 200 OK — playlist deleted
- 400 — missing or invalid playlist_id
- 403 — not allowed for this key
- 404 — playlist or customer key not found
- 500 — internal server error
5. List Playlists API
Returns all playlists for the customer key. Optionally filter by deviceid for sync checks between your panel and Orbix.
Endpoint
POST https://apis.orbixplay.com/list-playlistsHeaders
- Content-Type: application/json
- x-customer-key: <your-customer-key>
Request Body
{
"query": {
"deviceid": "<optional-device-id>"
}
}Fields
- deviceid (optional): If provided, only playlists for that device are returned. Omit to list all.
Response
- Success: 200 OK — { count, playlists: [{ playlist_id, deviceid, playlistName, username, password, host, ... }] }
- 400 — missing customer key
- 403 — not allowed for this key
- 404 — customer key not found
- 500 — internal server error
6. Get Single Playlist API
Returns the current data for one playlist by playlist_id.
Endpoint
POST https://apis.orbixplay.com/get-playlistHeaders
- Content-Type: application/json
- x-customer-key: <your-customer-key>
Request Body
{
"query": {
"playlist_id": "<playlist-id>"
}
}Fields
- playlist_id: Unique playlist ID to retrieve.
Response
- Success: 200 OK — { playlist: { playlist_id, deviceid, playlistName, username, password, host, ... } }
- 400 — missing or invalid playlist_id
- 403 — not allowed for this key
- 404 — playlist or customer key not found
- 500 — internal server error
7. Detect Slots / Available Slots API
Returns total, used, and remaining (available) slots for the subscriber. The email in the body must match the owner of the customer key.
Endpoint
POST https://apis.orbixplay.com/detect-slotsHeaders
- Content-Type: application/json
- x-customer-key: <your-customer-key>
Request Body
{
"query": {
"email": "<subscriber-email>"
}
}Fields
- email: Subscriber email address (must match the account linked to the customer key).
Response
- Success: 200 OK — returns email, role, total_slots, used_slots, remaining_slots
- 400 — missing customer key or email
- 403 — email does not match key owner or role is not subscriber
- 404 — customer key not found
- 500 — internal server error
8. Add List Code API
Registers a playlist source (DNS, username, password) and returns a listcode. Returns the same code if an identical source already exists for your account.
Endpoint
POST https://apis.orbixplay.com/add-list-codeHeaders
- Content-Type: application/json
- x-customer-key: <your-customer-key>
Request Body
{
"dns": "http://example.com:8080",
"username": "<username>",
"password": "<password>",
"playlistName": "<playlist-name>"
}Fields
- dns: Server URL or host (with or without http://).
- username: Playlist username.
- password: Playlist password.
- playlistName: Display name for the list code.
Response
- Success: 200 OK — { listcode, status: "created" }
- Success: 200 OK — { listcode, status: "already_exists" } (same subscriber + same credentials)
- 400 — missing or invalid parameters
- 401 — missing or invalid x-customer-key
- 403 — forbidden (subscriber role required)
- 500 — internal server error
9. Create Playlist from List Code API
Creates a playlist on a device using a listcode you own. Validates the device exists and enforces subscription slots.
Endpoint
POST https://apis.orbixplay.com/playlist-from-list-codeHeaders
- Content-Type: application/json
- x-customer-key: <your-customer-key>
Request Body
{
"listcode": 12345678,
"deviceid": "<device-id>",
"notes": "<optional-notes>"
}Fields
- listcode: Numeric list code returned by the Add List Code API.
- deviceid: Target device identifier (must exist in the database).
- notes (optional): Free-text notes stored on the playlist.
Response
- Success: 201 Created — { status: "added", playlist_id }
- 400 — missing required parameters
- 401 — missing or invalid x-customer-key
- 403 — forbidden, subscription expired, or slots exceeded
- 404 — device not found or listcode not found for this key
- 500 — internal server error
Notes
- All endpoints are POST requests to https://apis.orbixplay.com/
- The deviceid must already exist in the database before adding playlists.
- The customer key must belong to a subscriber account.
- Use playlist_id from Add Playlist for Update, Delete Single, and Get.
- List codes are scoped to your subscriber account — you cannot use another user's listcode.
