API Requests

The free Q-SYS Reflect API allows you to obtain a list of Q-SYS Cores, Systems, and items with relevant status. To submit a request to the Reflect API, you can use an application (for example, Postman) or a cURL command line tool.

Prerequisites

Note: Refer to the YAML file for the latest API support, as this feature is subject to change.

Example: Retrieve Info About All Cores in the Organization

This example uses the Postman application to submit an API request to obtain a list of Q-SYS Cores (and their details) within an Organization. Refer to the YAML file for a complete list of supported requests.

  1. Log in to Q-SYS Reflect as an Organization Owner.
  2. From the Q-SYS Reflect menu, click Organizations.
  3. Select an Organization from the list.
  4. Click API Tokens > + New Token.
  5. Specify a Token Name, and then click Add.
  6. Copy the token to a text file for use later.
  1. Open the YAML file (qrem-public-api.yaml) that you downloaded from Q-SYS Reflect.
  2. In the servers section, you'll see that the base URL for submitting API requests is https://reflect.qsc.com/api/public/v0. Your request will always include this URL, plus a supported path from the paths section.
  3. You'll see that one of the supported paths is /cores, which retrieves information for all Q-SYS Cores within an Organization. SoOr, the complete URL for the API request is thus:

    https://reflect.qsc.com/api/public/v0/cores

  4. Copy this URL and proceed to the next section.
  1. Open the Postman application.
  2. Import the YAML file by clicking on Import.
  3. Create and save a new Request:
    • Request Name: OrgCores
    • Request Description: "This request obtains a list of all Cores within my organization."
  4. In the GET field, paste the request URL: https://reflect.qsc.com/api/public/v0/cores
  5. Click the Authorization tab.
  6. In the Type drop-down menu, select Bearer Token.
  7. In the Token field, paste the token you created from Q-SYS Reflect.
  8. Click Send.

You should now see JSON text with a list of Q-SYS Cores in your Organization. For example:

Copy 
[
    {
        "id": 855,
        "serial": "3-12345A9B98CDEF9G1234GHI123JK987L2",
        "name": "MyCore-510i",
        "model": "Core 510i",
        "modelNumber": "Core 510i",
        "firmware": "8.2.0",
        "accessMode": "open",
        "uptime": 1570090458039,
        "status": {
            "code": 0,
            "message": "Running",
            "details": ""
        },
        "redundancy": null
    },
    {
        "id": 858,
        "serial": "1-2ABC01D2EF1234ZH9876GH6I123I1234",
        "name": "MyCore-110f",
        "model": "Core 110f",
        "modelNumber": "Core 110f",
        "firmware": "8.2.0",
        "accessMode": "open",
        "uptime": 1570138527982,
        "status": {
            "code": 7,
            "message": "Offline",
            "details": ""
        },
        "redundancy": null
    }
]

Example: Retrieve Media Playlists

This example uses the Postman application to submit an API request to obtain media playlists from a Q-SYS Core within an Organization. Refer to the YAML file for a complete list of supported requests.

  1. Log in to Q-SYS Reflect as an Organization Owner.
  2. From the Q-SYS Reflect menu, click Organizations.
  3. Select an Organization from the list.
  4. Click API Tokens > + New Token.
  5. Specify a Token Name, and then click Add.
  6. Copy the token to a text file for use later.
  1. Open the YAML file (qrem-public-api.yaml) that you downloaded from Q-SYS Reflect.
  2. In the servers section, you'll see that the base URL for submitting API requests is https://reflect.qsc.com/api/public/v0. Your request will always include this URL, plus a supported path from the paths section.
  3. You'll see that one of the supported paths is /cores/{coreId}/media_playlists, which retrieves the media playlists for all users within an Organization. So, the complete URL for the API request is thus:

    https://reflect.qsc.com/api/public/v0/cores/{coreId}/media_playlists

  4. Copy this URL and proceed to the next section.
  1. Open the Postman application.
  2. Import the YAML file by clicking on Import.
  3. Create and save a new Request:
    • Request Name: Media Playlists
    • Request Description: "This request obtains a list of all Media Playlists within my organization."
  4. In the GET field, paste the request URL: https://reflect.qsc.com/api/public/v0/cores/{coreId}/media_playlists
  5. Click the Authorization tab.
  6. In the Type drop-down menu, select Bearer Token.
  7. In the Token field, paste the token you created from Q-SYS Reflect.
  8. Click Send.

You should now see JSON text with media playlist data on your Q-SYS Core in your Organization. For example:

Copy 
{
  "id": "<uuid>",
  "count": "<integer>",
  "name": "<string>"
}

Example: Retrieve Users Sign In Audit Records

This example uses the Postman application to submit an API request to obtain sign in records of a user on a Q-SYS Core within an Organization. Refer to the YAML file for a complete list of supported requests.

  1. Log in to Q-SYS Reflect as an Organization Owner.
  2. From the Q-SYS Reflect menu, click Organizations.
  3. Select an Organization from the list.
  4. Click API Tokens > + New Token.
  5. Specify a Token Name, and then click Add.
  6. Copy the token to a text file for use later.
  1. Open the YAML file (qrem-public-api.yaml) that you downloaded from Q-SYS Reflect.
  2. In the servers section, you'll see that the base URL for submitting API requests is https://reflect.qsc.com/api/public/v0. Your request will always include this URL, plus a supported path from the paths section.
  3. You'll see that one of the supported paths is /users/audit-events', which retrieves sign in information for all users within an Organization. So, the complete URL for the API request is thus:

    https://reflect.qsc.com/api/public/v0/users/audit-events

  4. Copy this URL and proceed to the next section.
  1. Open the Postman application.
  2. Import the YAML file by clicking on Import.
  3. Create and save a new Request:
    • Request Name: Audit Events
    • Request Description: "This request obtains a list of all Audit Events within my organization."
  4. In the GET field, paste the request URL: https://reflect.qsc.com/api/public/v0/users/audit-events
  5. Click the Authorization tab.
  6. In the Type drop-down menu, select Bearer Token.
  7. In the Token field, paste the token you created from Q-SYS Reflect.
  8. Click Send.

You should now see JSON text with user sign in data on your Q-SYS Core in your Organization. For example:

Copy 
{
    "items": [
        {
            "id": 1652016,
            "dateTime": "2023-08-15T13:51:49Z",
            "message": "Jane Doe has signed in",
            "organizationName": "Fake Hotel, LLC",
            "siteName": "Oceanview",
            "systemName": "Core-610-Rack1",
            "userEmail": null,
            "userName": "Jane Doe",
            "userSystemRole": null,
            "userSiteRole": null,
            "userOrganizationRole": null
        },
        {
            "id": 1651910,
            "dateTime": "2023-08-14T21:58:35Z",
            "message": "SpecialK has signed in",
            "organizationName": "Fake Hotel, LLC",
            "siteName": "Oceanview",
            "systemName": "Core-610-Rack1",
            "userEmail": null,
            "userName": "John Doe",
            "userSystemRole": null,
            "userSiteRole": null,
            "userOrganizationRole": null
        },
        {
            "id": 1651907,
            "dateTime": "2023-08-14T21:43:17Z",
            "message": "John Doe has signed in",
            "organizationName": "Fake Hotel, LLC",
            "siteName": "Oceanview",
            "systemName": "Core-610-Rack1",
            "userEmail": null,
            "userName": "John Doe",
            "userSystemRole": null,
            "userSiteRole": null,
            "userOrganizationRole": null
        },
        {
            "id": 1651906,
            "dateTime": "2023-08-14T21:42:17Z",
            "message": "John Doe has signed in",
            "organizationName": "Fake Hotel, LLC",
            "siteName": "Oceanview",
            "systemName": "Core-610-Rack1",
            "userEmail": null,
            "userName": "John Doe",
            "userSystemRole": null,
            "userSiteRole": null,
            "userOrganizationRole": null
        },
        {
            "id": 1651905,
            "dateTime": "2023-08-14T21:42:12Z",
            "message": "John Doe has signed in",
            "organizationName": "Fake Hotel, LLC",
            "siteName": "Oceanview",
            "systemName": "Core-610-Rack1",
            "userEmail": null,
            "userName": "John Doe",
            "userSystemRole": null,
            "userSiteRole": null,
            "userOrganizationRole": null
        },
        {
            "id": 1651904,
            "dateTime": "2023-08-14T21:42:11Z",
            "message": "John Doe has signed in",
            "organizationName": "Fake Hotel, LLC",
            "siteName": "Oceanview",
            "systemName": "Core-610-Rack1",
            "userEmail": null,
            "userName": "John Doe",
            "userSystemRole": null,
            "userSiteRole": null,
            "userOrganizationRole": null
        }
    ],
    "total": 6
}

Troubleshooting

If your request returns "Unauthorized", check that you are sending the correct authorization:

  • Authorization Type is always Bearer Token.
  • Send the complete 64-character token. The token must still be active in the Tokens list within Q-SYS Reflect.

If your request returns "Not found", it means that the URL is incorrect.

  • The base URL (https://reflect.qsc.com/api/public/v0) is not a valid URL. You must append a valid path, such as /cores.
  • Refer to the YAML file for valid paths.