Management APIs
The following API endpoints are available on the Q-SYS Core processor for various management-related functions, including managing media content and playlists on the Core.
How to Submit Requests
To submit a request to these API endpoints, you can use an application (for example, Postman) or a cURL command line tool.
An API "bearer" token is required when Access Control is enabled on the Core – i.e., specific Users have been created in Core Manager. This is referred to as "protected" mode. If Access Control is not enabled on the Core ("open" mode), you do not need to create a token, and API requests are submitted without an Authorization header.
Note: Refer to the Authentication topic for details on what needs to be included in the request headers and body.
-
Open your API app.
-
Create a new POST request to the authentication URL. For example:
https://core-ip-address/api/v0/logon
-
Verify that the appropriate headers are being sent with the request. (In Postman, this is in the Headers tab.)
-
In the request body, include your Core username and password as a JSON array. (In Postman, this is in the Body tab in raw > JSON format). For example:
Copy{
"username": "myusername",
"password": "mypassword"
} -
Send the request.
-
The response is a single line that includes the token. Copy this token for subsequent API requests. For example:
-
From the API Endpoints section, select an endpoint – for example, Media Resources.
-
From the list of Requests, copy the URL for a request. For example, this is the URL for listing the folders and files in the root
/media
location:https://core-ip-address/api/v0/cores/self/media
-
In your API app, create a new GET request to that URL.
-
If Access Control is enabled on the Core, configure the request to send the bearer token with it. (In Postman, this is in the Authorization tab, with "Bearer Token" as type. Paste the token into the Token field.)
-
Submit the request.
You should now see a JSON-formatted response. For example, here is a response for requesting a listing of root files and folders:
Response
[
{
"path": "01 My Special Song.mp3",
"type": "file",
"name": "01 My Special Song",
"ext": "mp3",
"size": 14048450,
"created": 1619639517102,
"updated": 1619639519030,
"readOnly": false
},
{
"path": "Audio",
"type": "folder",
"name": "Audio",
"ext": null,
"size": null,
"created": 1511290661476,
"updated": 1607549583274,
"readOnly": true
},
{
"path": "Messages",
"type": "folder",
"name": "Messages",
"ext": null,
"size": null,
"created": 1511290661476,
"updated": 1614978982166,
"readOnly": true
},
{
"path": "MyFolder",
"type": "folder",
"name": "MyFolder",
"ext": null,
"size": null,
"created": 1619637060646,
"updated": 1619637060646,
"readOnly": false
},
{
"path": "PageArchives",
"type": "folder",
"name": "PageArchives",
"ext": null,
"size": null,
"created": 1511290661480,
"updated": 1551282017795,
"readOnly": true
},
{
"path": "Preambles",
"type": "folder",
"name": "Preambles",
"ext": null,
"size": null,
"created": 1511290661476,
"updated": 1511290661684,
"readOnly": true
},
{
"path": "Ringtones",
"type": "folder",
"name": "Ringtones",
"ext": null,
"size": null,
"created": 1511290661476,
"updated": 1535728270992,
"readOnly": true
},
]
Note: If you see an "Unauthorized" response, it means you forgot to include the bearer token in the request.
API Endpoints
Authentication
Request or revoke a bearer token for other API endpoint requests. A bearer token is required if Access Control is enabled on the Q-SYS Core processor.
Media Resources
View and manage /media
content on the Core, including folders and files.
Media Playlists
View and manage audio playlists on the Core.