Assets

Get an image

GET/v1/assets/{assetId}

No API keyNot rate-limited · cached 1 hour

An image Rankd hosts, such as a profile picture (avatarUrl points here). Returns the image, not JSON. Responses are cached at the edge for an hour, carry an ETag (send it back in If-None-Match for a 304), allow any origin, and are not rate-limited.

Parameters#

Path parameters#

Name	Type	Description
assetIdrequired	string	`ast_` then 26 characters. Pattern: `^ast_[0-9A-Z]{26}$` · Example: `ast_9E07Q6Q598DXKRQBN0NDSCQYA4`

Headers#

Name	Type	Description
If-None-Match	string	The `ETag` of a copy you already have.

Try it: open the example image. Images are ordinary URLs, so they work straight in an <img> tag.

Request#

curl -o avatar.jpg "https://api.rankdmusic.app/v1/assets/ast_9E07Q6Q598DXKRQBN0NDSCQYA4"

const response = await fetch('https://api.rankdmusic.app/v1/assets/ast_9E07Q6Q598DXKRQBN0NDSCQYA4');
if (!response.ok) throw new Error(`Rankd API: ${response.status}`);
const image = await response.blob(); // image/jpeg, image/png…

import Foundation

let url = URL(string: "https://api.rankdmusic.app/v1/assets/ast_9E07Q6Q598DXKRQBN0NDSCQYA4")!
let (data, response) = try await URLSession.shared.data(from: url)
guard (response as? HTTPURLResponse)?.statusCode == 200 else { throw URLError(.badServerResponse) }
// data is the image: UIImage(data: data) on iOS

import requests

response = requests.get("https://api.rankdmusic.app/v1/assets/ast_9E07Q6Q598DXKRQBN0NDSCQYA4", timeout=10)
response.raise_for_status()
with open("avatar.jpg", "wb") as file:
    file.write(response.content)

Responses#

200The image. Content-Type is the image’s own type, such as image/jpeg.

Headers: ETag A fingerprint of the image. · Cache-Control Always public, max-age=3600.

304The copy you have (from If-None-Match) is current.

404No such image, or what showed it is no longer public.

Captured from production: GET /v1/assets/ast_00000000000000000000000000

404 response

{
  "error": {
    "code": "not_found",
    "message": "Asset not found."
  }
}