Background

The CrateQ API is the back-end engine to the CrateQ Widget and Desktop App, a native, cross-platform desktop app where DJ's can sign-in to one place to access, search, and download accross a growing list of DJ digital outlets and content distributors, A.K.A. DJ record pools (such as SmashVision, Late Night Record Pool, and soon IDJ, Direct Music Service, and more). The CrateQ Widget also operates like a plugin for all the major DJ desktop softwares (Serato, RekordBox, Virual DJ, etc). Features include:

• Search, preview, queue, and download audio or video from all of your favorite records pools
• Advance search/filter on all data fields (genre(s)/sub-genre(s), bpm range, editors, mix, keywords, year range, etc) accross all records pools at once
• Drag and drop files directly from crateQ into any DJ software
• View and manage your song queue, wish list, playlists, crate, bin, favorites, etc (syncs with your record pool websites and mobile apps)
• Batch download and auto-download features of song queue
• Toggle between widget mode, app mode (resizable window), or fullscreen mode allowing users to use crateQ in a live environment
• Widget mode is designed to float on top of the DJ software and can be positioned anywhere on the screen for easy access
• Custom column views can be added or removed (artist, title, BPM, genre, release year, editor, length, etc)

API Overview

The CrateQ API offers two types of integrations: DJ/DVS Software Integration and DJ Record Pool Integration.

DJ/DVS Software Integration: The CrateQ API has made it simple for DJ/DVS Software providers to integrate licensed DJ Record Pool content into their software and/or platform. With crateQ's growing number of DJ Record Pool providers/partners, the CrateQ API has established a consistant data structure and mapping convention accross all its DJ Record Pools. This normalized-relational data structure simplifies authentication, searching, file retrival/streaming, etc, with its open RESTful API access to the entire data stucture. Other features include:

• Real-time music content updates from each DJ Record Pool so content data is always synced and indexed, including charts, trending, playlists, download history, etc.
• Rich search experiences using AI enable Azure Cognitive Services with custom Machine Learning (ML) algorithms for results scoring/weighting, facet navigation and advance filters, synonyms, auto-complete, and text analysis, auto-corrected search terms, and more.
• Simple sorting (multi-column), paging (customize rows per page), result limits, etc.
• Secure stream chunked byte array suitable for file streaming and direct file download.

DJ Record Pool Integration: The CrateQ API Integration includes endpoints to streamline the onboarding and data scyncronization for DJ Record Pools, their respective music catalog, playlists, queues, charts, trending, etc. This allows DJ Record Pool members the ability to leverage CrateQ Widget and Desktop App as an added services. Please visit crateq.com For more information on the features CrateQ Widget and Desktop App.

See the DJ Record Pool Integration documentation for more info.

API Access

The CrateQ API is a set of HTTP endpoints and data models that demonstrates 3rd party integration and configuration. The CrateQ API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use HTTP GET requests with URL parameters/arguments and JSON responses, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing (CORS) from partner domains, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website's client-side code). JSON is returned by all API responses, including errors. For catalog searching, queueing, and download, users must first login via the authentication endpoints described in the User Authentication docuentation, and pass the expiring JSON Web Token (JWT) in the Authorization (Bearer) HTTP Header of the call.

Check out our full documentation to learn about everything you can do with the API. If there is any customization changes needed in results, arguments, format, or anything else to meet your requirements, please Contact Us, and we would be glad to assist.

Requests

API Key: Request authentication is via an API key, which is a required URL parameter. Please Contact Us to receive your API key. If you do not include you API key in your request, you will receive a HTTP 403 (Forbidden) error response. Furthermore, all request are IP restricted. All 3rd party application must provide the IP address(es) that will be accessing the CrateQ API for unrestricted access.

API Queries: Once you've got your API key you can use a browser or any HTTP client to make a simple query/request to the CrateQ API. The API key is passed as a parameter called key along with other search parameters. For example:

https://api.crateq.com/api/User/Add?key=1a7ab675433719c540a6300f17b4a531

API Methods: GET, POST, and PUT are the HTTP metheds accepted by the API. Only one method is accepted per endpoint.

HTTP Headers: All requests must specify an HTTP header of Content-Type: application/json and Authorization: Bearer JWT_GOES_HERE (please see the User Authentication documentation for more information on obtaining the JWT).

Responses

Data Format: All data endpoint responses from the CrateQ API are formatted in JSON. The responses are minified, so if you want to review the responses in a human readable format you will have to post-process them.

Date Format: All dates in the API are strings in the ISO 8601 "combined date and time representation" format (i.e. 2007-04-05T14:30), using UTC time.

Error Handling

Our API libraries raise exceptions for many reasons, such as invalid parameters, authentication errors, and network unavailability. We recommend writing code that gracefully handles all possible API exceptions.

We use conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success and codes in the 4xx range indicate an error that failed. Below are some common errors:

200 (Timeout): The request timed-out (See Timeouts below for more details).

400 (Parameter Required): A required parameter was not included.

403 (Forbidden): Your key parameter was either not included or invalid.

404 (Resource Not Found): Invalid Endpoint/URL.

500 (Exception Thrown): Other miscellaneous exception/error.

Timeouts: Currently, if no results are found after 30 seconds, the CrateQ API will abruptly terminate the request and return no more results. In this case, a HTTP 200 result is still returned. If the HTTP 200 Error Status Code is not returned, the response will be an empty JSON response like the following:

[]

Error Response: Errors always returns the following JSON data model:

    {
        "status":500,
        "message":"Username and Password are required."
    }
    

Overview

The CrateQ API Integration includes endpoints to streamline the onboarding and data scyncronization for DJ Record Pools, their respective music catalog, playlists, queues, charts, trending, etc. This allows DJ Record Pool members the ability to leverage CrateQ Widget and Desktop App as an added services. Please visit crateq.com For more information on the features CrateQ Widget and Desktop App.

The CrateQ API RESTful data endpoints available for DJ Record Pool Integration include: Music Catalog Syncronization, User Authentication, Download/Authentication, Download History and Charts, Content Queue for Batch Downloading, and Download Syncronization

Music Catalog Syncronization

To initialize implementation, DJ Record Pools must provide a one-time data dump of all content data (i.e. artist, title, bpm, etc) and all lookup tables (i.e. genres, etc). CrateQ will create a data migration map DJ Record Pool data structure to automatically map to CrateQ data structure. CrateQ will import all DJ Record Pool music catalog data. Data files must be submitted via Secure File Transfer Protocol (SFTP). Supported data formats are CSV, XML, JSON, and SQL.

Description: For all new, updated, or deleted songs the DJ Record Pool will simply do a POST the following CrateQ API endpoint with the new or updated song data.

http://api.crateq.com/api/UpdateMediaFunction/[your song ID to update]?key=[your DJ Record Pool API key]

HTTP Method: POST

Note: To simplify the updates, specs on POST properties for the updates will be provided once the DJ Record Pool/CrateQ mapping is complete.

Song Update Arguements: originatorId, artist, title, genreIds, genreCategoryId, playlistDate, bpm, length, mix, editor, releaseYear, mediaFile, mediaType, groupId, qualityId and dateUpdated (See details below)

User Authentication

Description: Participating DJ Record Pool are required to have one of only two open RESTful Endpoint to allow the the CreateQ API to authenticate the member/user. The CrateQ Widget and Desktop App will authenticate against this endpoint each login/sign-in of he app, everytime and song (from the DJ Record Pool's music cataglog) is queued, and before everytime a song or video (from the DJ Record Pool's music cataglog) is downloaded or streamed.

[URL Provided by DJ Record Pool]

HTTP Method: POST

User Authentication Arguements: username and password (See details below)

User Authentication Response Properties: Always returns the following JSON data model:

        
    [
        {
            "userId":12345,
            "msg":"",
            "email":"test@test.com",
            "status":"current",
            "plan":"pro",
            "renewal":"2019-06-01",
            "country":"",
            "crateq":false
        }
    ]
    

Content Queue / Batch Download

Description: An endpoint for DJ Record Pool users to view and maintain seperate list know as the "Download Queue". The Download Queue provides the crateQ Desktop Widget a list to batch download all queued tracks on a schedule or automatically (in background mode) when queued from any of the participating DJ Record Pools (via this API), the crateQ mobile app, or crateQ Desktop Widget.

https://api.crateq.com/api/Content/Queue?key=1a7ab675433719c540a6300f17b4a531

HTTP Method: GET

Queue List Properties: Always returns the following JSON data model, with the default sort by queueDate desc:

        
    {
        "records":2,
        "message":"0-2",
        "pages":1,
        "page":1,
        "sort":"queueDate",
        "dir":"desc",
        "data":[
            {
                "mediaId":132692,
                "artist":"Bando Jonez feat LaRon and Polow Da Don",
                "title":"Wet [Dirty Acc]",
                "genre":"R&B",
                "bpm":72,
                "length":"2:18",
                "tool":"Acapella",
                "editor":"",
                "advisory":"Clean",
                "releaseYear":2019,
                "quality":"",
                "preview":"https://api.crateq.com/api/Content/Preview/141453?token=7693u337730o0d23fg35",
                "date":"2019-05-13",
                "auth":"d3236a91ae651eb57b20b8b469950e23a09f5434",
                "queueId":1572993,
                "downloaded":false,
                "audio":true,
                "video":true,
                "source":"lnrp",
                "img":"",
                "queueDate":"2021-04-27"
            },
            {
                "mediaId":283482,
                "artist":"Q-Unique feat Cappadonna, Taking Back Sunday and DJ Eclipse",
                "title":"Verrazzano Villians [Clean]",
                "genre":"Hip-Hop > East",
                "bpm":86,
                "length":"4:49",
                "tool":"Extended",
                "editor":"",
                "advisory":"Clean",
                "releaseYear":2021,
                "quality":"",
                "preview":"https://api.crateq.com/api/Content/Preview/141453?token=3456ydt8898689983",
                "date":"2021-04-25",
                "auth":"f35fd1db93672aab7a2156e42aa0b2b590fcde6b",
                "queueId":1572992,
                "downloaded":false,
                "audio":true,
                "video":true,
                "source":"lnrp",
                "img":"",
                "queueDate":"2021-04-26"
            },
            [etc...]
        ]
    }
    

Update Queue

Description: An endpoint that allows all users of participating DJ Record Pools to add or removes audio and video tracks to the Download Queue.

https://api.crateq.com/api/Content/UpdateQueue?key=1a7ab675433719c540a6300f17b4a531

HTTP Method: POST

Queue Arguements: queueId, mediaId, originatorId, and userId (See details below)

Update Queue Response Properties: Always returns the following JSON data model:

        
    [
        {
            "id": 1572989,
            "message": "Media added to queue."
        }
    ]
    

Content Download

The second endpoint DJ Record Pool's are required to create is for content download via RPC (Remote Procedure Call) where an encrypted token and song/user arguments are passed to dynamically generate a download file stream. CrateQ has created code samples for some of the most popular API/Server-Side languages including C#, NodeJS, and PHP so decrypt the arguements and authenticate the token. The auth property is token which is unique for every song in the music catalog response (See Music Catalog Documentation for details). This auth property is also unique for every user and has a 15 minute validation period from the time it is deplayed in the music catalog response.