CosmosAsync

Asyncronous Cosmos API wrapper used by the Spotify client. It is used to make requests to the Spotify client's internal API as well as external URLs.

Spicetify.CosmosAsync

It works similarly to fetch or axios but for each request it will automatically add the required headers and cookies (such as user session token). All responses are parsed as JSON.

caution

Be mindful of where you're making a request to, especially if you're making a request to an external URL as it may compromise the user's account.

If you're not certain, only use CosmosAsync for internal Spotify URLs, or use fetch for external URLs.

tip

Feel free to reach out to the developers' community on Discord if you need help with any of these methods, or if you need a list of all available internal/useful endpoints.

Methods

namespace CosmosAsync {
    function head(url: string, headers?: Headers): Promise<Headers>;
    function get(url: string, body?: Body, headers?: Headers): Promise<Response["body"]>;
    function post(url: string, body?: Body, headers?: Headers): Promise<Response["body"]>;
    function put(url: string, body?: Body, headers?: Headers): Promise<Response["body"]>;
    function del(url: string, body?: Body, headers?: Headers): Promise<Response["body"]>;
    function patch(url: string, body?: Body, headers?: Headers): Promise<Response["body"]>;
    function sub(url: string, callback: ((b: Response["body"]) => void), onError?: ((e: Error) => void), body?: Body, headers?: Headers): Promise<Response["body"]>;
    function postSub(url: string, body: Body | null, callback: ((b: Response["body"]) => void), onError?: ((e: Error) => void)): Promise<Response["body"]>;
    function request(method: Method, url: string, body?: Body, headers?: Headers): Promise<Response>;
    function resolve(method: Method, url: string, body?: Body, headers?: Headers): Promise<Response>;
}

It is worth noting that you can either make a request using the request method, or use the shorthand methods for each HTTP method.

For example, you can fetch the current client version using either of the following:

await Spicetify.CosmosAsync.get("sp://desktop/v1/version");

or

await Spicetify.CosmosAsync.request("GET", "sp://desktop/v1/version");

For a complete list of available HTTP methods, see Method.

You can also use CosmosAsync for Spotify Web API endpoints without having to manually add the required headers and cookies.

// All endpoints that uses the `sp`, `wg`, and `hm` protocol are internal Spotify endpoints
await Spicetify.CosmosAsync.get("sp://desktop/v1/version");

// Spotify Web API endpoints also works
await Spicetify.CosmosAsync.get("https://api.spotify.com/v1/me");

// Requests to external URLs are NOT safe and may compromise the user's account
// Only use this if you're certain that the URL is safe
// If you need to make a request to an external URL, use `fetch` instead
await fetch("https://example.com");

head

Make a HEAD request to the specified URL.

function head(url: string, headers?: Headers): Promise<Headers>;

Parameter	Type	Description
url	string	URL to make the request to.

get

Make a GET request to the specified URL.

function get(url: string, body?: Body, headers?: Headers): Promise<Response["body"]>;

Parameter	Type	Description
url	string	URL to make the request to.
body	Body	Request body.
headers	Headers	Request headers.

Example:

// Get all playlists in user's library
const res = await Spicetify.CosmosAsync.get("sp://core-playlist/v1/rootlist");
const playlists = res.rows.filter((row) => row.type === "playlist");

post

Make a POST request to the specified URL.

function post(url: string, body?: Body, headers?: Headers): Promise<Response["body"]>;

Parameter	Type	Description
url	string	URL to make the request to.
body	Body	Request body.
headers	Headers	Request headers.

Example:

// Skip to the next track in queue
const res = await Spicetify.CosmosAsync.post("sp://player/v2/main/skip_next");

put

Make a PUT request to the specified URL.

function put(url: string, body?: Body, headers?: Headers): Promise<Response["body"]>;

Parameter	Type	Description
url	string	URL to make the request to.
body	Body	Request body.
headers	Headers	Request headers.

Example:

// Enable/disable incognito mode
const res = await Spicetify.CosmosAsync.put("sp://scrobble/v1/incognito", { enabled: boolean });

del

Make a DELETE request to the specified URL.

function del(url: string, body?: Body, headers?: Headers): Promise<Response["body"]>;

Parameter	Type	Description
url	string	URL to make the request to.
body	Body	Request body.
headers	Headers	Request headers.

patch

Make a PATCH request to the specified URL.

function patch(url: string, body?: Body, headers?: Headers): Promise<Response["body"]>;

Parameter	Type	Description
url	string	URL to make the request to.
body	Body	Request body.
headers	Headers	Request headers.

sub

Make a SUB request to the specified URL.

function sub(url: string, callback: ((b: Response["body"]) => void), onError?: ((e: Error) => void), body?: Body, headers?: Headers): Promise<Response["body"]>;

Parameter	Type	Description
url	string	URL to make the request to.
callback	(b: Response["body"]) => void	Callback function to run when the request is successful.
onError	(e: Error) => void	Callback function to run when the request fails.
body	Body	Request body.
headers	Headers	Request headers.

postSub

Make a POST request to the specified URL, and subscribe to the response.

function postSub(url: string, body: Body | null, callback: ((b: Response["body"]) => void), onError?: ((e: Error) => void)): Promise<Response["body"]>;

Parameter	Type	Description
url	string	URL to make the request to.
body	Body	Request body.
callback	(b: Response["body"]) => void	Callback function to run when the request is successful.
onError	(e: Error) => void	Callback function to run when the request fails.

request

Make a request to the specified URL.

function request(method: Method, url: string, body?: Body, headers?: Headers): Promise<Response>;

Parameter	Type	Description
method	Method	HTTP method to use.
url	string	URL to make the request to.
body	Body	Request body.
headers	Headers	Request headers.

resolve

Make a request to the specified URL, and resolve the response.

function resolve(method: Method, url: string, body?: Body, headers?: Headers): Promise<Response>;

Parameter	Type	Description
method	Method	HTTP method to use.
url	string	URL to make the request to.
body	Body	Request body.
headers	Headers	Request headers.