{ "openapi": "3.1.0", "info": { "title": "Rankd API", "version": "1", "summary": "Ratings, reviews, lists and community charts from Rankd.", "description": "The public, read-only part of the Rankd API. No credentials are needed. Every endpoint returns only what Rankd already shows to someone who is not signed in: public profiles, public ratings, reviews and lists, community charts, and the Apple Music catalogue as Rankd presents it.", "contact": { "name": "Rankd", "url": "https://rankdmusic.app" } }, "servers": [ { "url": "https://api.rankdmusic.app", "description": "Production" } ], "security": [], "tags": [ { "name": "API", "description": "The API itself: its version and health." }, { "name": "Discovery", "description": "What the Rankd community is rating right now." }, { "name": "Music", "description": "Albums, songs and artists from the Apple Music catalogue, with Rankd’s community numbers." }, { "name": "Search", "description": "Find people and public lists." }, { "name": "Users", "description": "Public profiles and what people have chosen to make public." }, { "name": "Lists", "description": "Public ranked lists and collections." }, { "name": "Reviews", "description": "Public reviews." }, { "name": "Assets", "description": "Images Rankd hosts, such as profile pictures." } ], "paths": { "/v1": { "get": { "operationId": "getApi", "tags": [ "API" ], "summary": "API root", "description": "Names the API and its version. A good first request.", "responses": { "200": { "description": "The API and its version.", "x-request": "/v1", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ApiInfo" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "data": { "name": "Rankd API", "version": 1, "documentation": "docs/api/v1.md" }, "meta": { "apiVersion": 1, "migrationPhase": 3, "sourceOfTruth": "per_account" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/health": { "get": { "operationId": "getHealth", "tags": [ "API" ], "summary": "Health check", "description": "Whether the API is up and can reach its database. This site’s status indicator uses it. It counts toward your rate limit like any other request.", "responses": { "200": { "description": "The API answered. `database` says whether it could query its data.", "x-request": "/v1/health", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Health" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "data": { "database": "ok" }, "meta": { "apiVersion": 1, "migrationPhase": 3, "sourceOfTruth": "per_account" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "The API is running without its database.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "database_unavailable", "message": "The Rankd database is not bound to this deployment." } } } } } } } }, "/v1/discover": { "get": { "operationId": "getDiscover", "tags": [ "Discovery" ], "summary": "Discover", "description": "Trending albums, recent public reviews, recent public lists and active members, in one request.", "responses": { "200": { "description": "The Discover page.", "x-request": "/v1/discover", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Discover" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "data": { "trendingAlbums": [ { "music": { "provider": "apple_music", "type": "album", "id": "697194953", "title": "Discovery", "artistName": "Daft Punk", "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/fd/4a/77/fd4a77db-0ebc-d043-41a2-f32fa1bb0fb4/dj.qrikkdwj.jpg/600x600bb.jpg" }, "artworkTemplate": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/fd/4a/77/fd4a77db-0ebc-d043-41a2-f32fa1bb0fb4/dj.qrikkdwj.jpg/{w}x{h}bb.jpg", "ratingCount": 4, "averageRating": 98 }, { "music": { "provider": "apple_music", "type": "album", "id": "1889992111", "title": "you seem pretty sad for a girl so in love", "artistName": "Olivia Rodrigo", "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/1d/1b/f9/1d1bf9b1-44c6-9a6c-6ffb-c158488c06ce/26UMGIM39303.rgb.jpg/600x600bb.jpg" }, "artworkTemplate": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/1d/1b/f9/1d1bf9b1-44c6-9a6c-6ffb-c158488c06ce/26UMGIM39303.rgb.jpg/{w}x{h}bb.jpg", "ratingCount": 4, "averageRating": 92 } ], "recentReviews": [ { "id": "2ea78192-78b7-49c9-80d0-893d247e4787", "username": "kyle", "displayName": "kyle", "avatarUrl": "https://api.rankdmusic.app/v1/assets/ast_9E07Q6Q598DXKRQBN0NDSCQYA4", "music": { "provider": "apple_music", "type": "song", "id": "1590368894", "title": "All Too Well (10 Minute Version) [Taylor's Version] [From The Vault]", "artistName": "Taylor Swift", "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music115/v4/15/38/9b/15389bf4-8074-06c3-11ee-655b5453af68/21UM1IM25046.rgb.jpg/600x600bb.jpg" }, "artworkTemplate": "https://is1-ssl.mzstatic.com/image/thumb/Music115/v4/15/38/9b/15389bf4-8074-06c3-11ee-655b5453af68/21UM1IM25046.rgb.jpg/{w}x{h}bb.jpg", "body": "amazing 🤩", "containsSpoilers": false, "ratingValue": 100, "createdAt": "2026-09-29T17:48:53.928Z" }, { "id": "5e8e7447-a3d0-4cd0-86a3-f5849df4a9f7", "username": "kyle", "displayName": "kyle", "avatarUrl": "https://api.rankdmusic.app/v1/assets/ast_9E07Q6Q598DXKRQBN0NDSCQYA4", "music": { "provider": "apple_music", "type": "song", "id": "570216128", "title": "Real Gone Kid", "artistName": "Deacon Blue", "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music/v4/2b/ec/6c/2bec6ca0-fee4-d425-d4cf-b6b3d786b0f2/886443693197.jpg/600x600bb.jpg" }, "artworkTemplate": "https://is1-ssl.mzstatic.com/image/thumb/Music/v4/2b/ec/6c/2bec6ca0-fee4-d425-d4cf-b6b3d786b0f2/886443693197.jpg/{w}x{h}bb.jpg", "body": "Unreal song", "containsSpoilers": false, "ratingValue": 100, "createdAt": "2026-09-12T09:43:23.142Z" } ], "recentLists": [ { "id": "9c56fe92-4ac1-463d-af4b-bbadfd11e5eb", "ownerUsername": "kyle", "ownerDisplayName": "kyle", "title": "Songs I don’t rate", "description": "", "emoji": "", "entryCount": 0, "updatedAt": "2026-09-29T20:36:57.231Z" }, { "id": "1082404f-6402-437b-a137-89b585754d74", "ownerUsername": "kyle", "ownerDisplayName": "kyle", "title": "My 5★ Albums", "description": "", "emoji": "🌟", "entryCount": 14, "updatedAt": "2026-09-29T13:15:54.311Z" } ], "activeMembers": [ { "id": "usr_01KY0JGXMWTT8H9WFN9RTM5JP9", "username": "kyle", "displayName": "kyle", "avatarUrl": "https://api.rankdmusic.app/v1/assets/ast_9E07Q6Q598DXKRQBN0NDSCQYA4", "foundingMember": { "number": 2 }, "ratingCount": 725 } ] }, "meta": { "apiVersion": 1, "migrationPhase": 3, "sourceOfTruth": "per_account" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/feed/for-you": { "get": { "operationId": "getForYouFeed", "tags": [ "Discovery" ], "summary": "Community feed", "description": "The community feed. Without credentials it is the same for everyone, and `meta.personalized` is `false`. Cards come in several types, each with its own fields. Skip types your client does not know: new ones are added without a new API version.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "How many items to return. Default 20, at most 40. Larger values are capped at 40; anything that is not a positive whole number gives the default.", "schema": { "type": "integer", "minimum": 1, "maximum": 40, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.nextCursor` of the previous page. Leave it out for the first page. Cursors are opaque: pass them back unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of feed cards.", "x-request": "/v1/feed/for-you?limit=40", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FeedCard" } }, "meta": { "$ref": "#/components/schemas/FeedMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "data": [ { "id": "list:1082404f-6402-437b-a137-89b585754d74", "type": "list", "createdAt": "2026-09-29T13:15:54.311Z", "actor": { "id": "usr_01KY0JGXMWTT8H9WFN9RTM5JP9", "username": "kyle", "displayName": "kyle", "avatarUrl": "https://api.rankdmusic.app/v1/assets/ast_9E07Q6Q598DXKRQBN0NDSCQYA4" }, "list": { "id": "1082404f-6402-437b-a137-89b585754d74", "title": "My 5★ Albums", "description": "", "emoji": "🌟", "kind": "collection", "entryCount": 14, "covers": [ "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/58/8f/a9/588fa9a2-7cc5-f02c-9ce6-c986e0dc1c15/25UM1IM19577.rgb.jpg/{w}x{h}bb.jpg", "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/eb/e6/06/ebe606da-e00f-82d3-47f3-b79904eed541/17UM1IM24651.rgb.jpg/{w}x{h}bb.jpg" ] }, "engagement": { "reactions": 0, "comments": 0, "likes": 0, "saves": 0 }, "reason": "Community list" }, { "id": "trending:album:697194953", "type": "trending", "createdAt": "2026-09-30T11:14:42.530Z", "music": { "type": "album", "id": "697194953", "title": "Discovery", "artistName": "Daft Punk", "albumId": null, "albumTitle": null, "artworkTemplate": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/fd/4a/77/fd4a77db-0ebc-d043-41a2-f32fa1bb0fb4/dj.qrikkdwj.jpg/{w}x{h}bb.jpg", "releaseYear": 2001, "genre": "Dance" }, "stats": { "raters": 4, "average": 98, "thisWeek": 2 }, "period": "this month", "reason": "Trending on Rankd" } ], "meta": { "apiVersion": 1, "migrationPhase": 3, "sourceOfTruth": "per_account", "nextCursor": null, "personalized": false, "coldStart": true } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/charts": { "get": { "operationId": "getCharts", "tags": [ "Discovery" ], "summary": "Rankd Charts", "description": "The community’s weekly chart, built from Rankd ratings: each entry’s rank, how it moved since last week, and its community average.", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "What to chart.", "schema": { "type": "string", "enum": [ "album", "song", "artist", "music_video" ], "default": "album" }, "example": "album" }, { "name": "limit", "in": "query", "required": false, "description": "How many items to return. Default 20, at most 50. Larger values are capped at 50; anything that is not a positive whole number gives the default.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "This week’s chart.", "x-request": "/v1/charts?type=album&limit=2", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Chart" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "data": { "type": "album", "window": "week", "generatedAt": "2026-09-30T11:14:42.709Z", "entries": [ { "rank": 1, "previousRank": 5, "movement": "up", "change": 4, "music": { "type": "album", "id": "697194953", "title": "Discovery", "artistName": "Daft Punk", "albumId": null, "albumTitle": null, "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/fd/4a/77/fd4a77db-0ebc-d043-41a2-f32fa1bb0fb4/dj.qrikkdwj.jpg/600x600bb.jpg", "releaseYear": 2001 }, "community": { "average": 97.5, "count": 4 }, "rankedThisWeek": 2 }, { "rank": 2, "previousRank": 13, "movement": "up", "change": 11, "music": { "type": "album", "id": "1590368448", "title": "Red (Taylor’s Version) [+ A Message from Taylor]", "artistName": "Taylor Swift", "albumId": null, "albumTitle": null, "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music115/v4/15/38/9b/15389bf4-8074-06c3-11ee-655b5453af68/21UM1IM25046.rgb.jpg/600x600bb.jpg", "releaseYear": 2021 }, "community": { "average": 91.3, "count": 4 }, "rankedThisWeek": 2 } ] }, "meta": { "apiVersion": 1, "migrationPhase": 3, "sourceOfTruth": "per_account" } } } } }, "400": { "description": "`type` is not something Rankd charts.", "x-request": "/v1/charts?type=playlist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_type", "message": "Charts are for album, song, artist or music_video." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/music/search": { "get": { "operationId": "searchMusic", "tags": [ "Music" ], "summary": "Search the catalogue", "description": "Searches the Apple Music catalogue. Results are grouped by type: one key for each type you asked for that had matches.", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "What to search for. At least two characters; only the first 120 are used.", "schema": { "type": "string", "minLength": 2 }, "example": "discovery daft punk" }, { "name": "types", "in": "query", "required": false, "description": "Comma-separated: any of `album`, `artist` and `song`.", "schema": { "type": "string", "default": "album,artist,song" }, "example": "album,song" }, { "name": "limit", "in": "query", "required": false, "description": "How many items to return. Default 10, at most 25. Larger values are capped at 25; anything that is not a positive whole number gives the default.", "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 } } ], "responses": { "200": { "description": "Matches, grouped by type.", "x-request": "/v1/music/search?q=discovery%20daft%20punk&types=album,song&limit=1", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MusicSearchResults" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "data": { "song": [ { "provider": "apple_music", "type": "song", "id": "697195633", "title": "Digital Love", "artistName": "Daft Punk", "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/fd/4a/77/fd4a77db-0ebc-d043-41a2-f32fa1bb0fb4/dj.qrikkdwj.jpg/600x600bb.jpg", "artworkTemplate": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/fd/4a/77/fd4a77db-0ebc-d043-41a2-f32fa1bb0fb4/dj.qrikkdwj.jpg/{w}x{h}bb.jpg", "releaseYear": 2001 } ], "album": [ { "provider": "apple_music", "type": "album", "id": "697194953", "title": "Discovery", "artistName": "Daft Punk", "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/fd/4a/77/fd4a77db-0ebc-d043-41a2-f32fa1bb0fb4/dj.qrikkdwj.jpg/600x600bb.jpg", "artworkTemplate": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/fd/4a/77/fd4a77db-0ebc-d043-41a2-f32fa1bb0fb4/dj.qrikkdwj.jpg/{w}x{h}bb.jpg", "releaseYear": 2001 } ] }, "meta": { "apiVersion": 1, "migrationPhase": 3, "sourceOfTruth": "per_account" } } } } }, "400": { "description": "`q` is shorter than two characters.", "x-request": "/v1/music/search?q=a", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_query", "message": "Search for at least two characters." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "503": { "description": "The catalogue is not configured on this deployment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "catalogue_unavailable", "message": "The music catalogue is not configured on this deployment." } } } } } } } }, "/v1/music/{type}/{id}": { "get": { "operationId": "getMusicItem", "tags": [ "Music" ], "summary": "Get an album, song or artist", "description": "One catalogue item as Rankd shows it: Apple Music’s details plus Rankd’s community numbers. Which fields are filled in depends on `type`. An album has `tracks`; an artist has `albums`, `singles`, `topSongs` and `similarArtists`; a song has its `album`. Fields that do not apply are empty arrays or `null`.", "parameters": [ { "name": "type", "in": "path", "required": true, "description": "What kind of catalogue item.", "schema": { "type": "string", "enum": [ "album", "song", "artist" ] }, "example": "album" }, { "name": "id", "in": "path", "required": true, "description": "The Apple Music catalogue id.", "schema": { "type": "string", "pattern": "^[0-9]{1,15}$" }, "example": "697194953" } ], "responses": { "200": { "description": "The item and its community numbers.", "x-request": "/v1/music/album/697194953", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MusicItem" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "data": { "music": { "provider": "apple_music", "type": "album", "id": "697194953", "title": "Discovery", "artistName": "Daft Punk", "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/fd/4a/77/fd4a77db-0ebc-d043-41a2-f32fa1bb0fb4/dj.qrikkdwj.jpg/600x600bb.jpg" }, "artworkTemplate": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/fd/4a/77/fd4a77db-0ebc-d043-41a2-f32fa1bb0fb4/dj.qrikkdwj.jpg/{w}x{h}bb.jpg", "releaseDate": "2001-03-12", "releaseYear": 2001, "genreNames": [ "Dance", "House" ], "trackCount": 14, "tracks": [ { "provider": "apple_music", "type": "song", "id": "697195462", "title": "One More Time", "artistName": "Daft Punk", "albumTitle": "Discovery", "trackNumber": 1, "discNumber": 1, "durationSeconds": 320, "isExplicit": false, "previewUrl": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview221/v4/5d/93/d8/5d93d83f-ad1e-da4d-1d79-9937bdff24ec/mzaf_14396932211949300852.plus.aac.p.m4a", "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/fd/4a/77/fd4a77db-0ebc-d043-41a2-f32fa1bb0fb4/dj.qrikkdwj.jpg/600x600bb.jpg", "artworkTemplate": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/fd/4a/77/fd4a77db-0ebc-d043-41a2-f32fa1bb0fb4/dj.qrikkdwj.jpg/{w}x{h}bb.jpg" }, { "provider": "apple_music", "type": "song", "id": "697195570", "title": "Aerodynamic", "artistName": "Daft Punk", "albumTitle": "Discovery", "trackNumber": 2, "discNumber": 1, "durationSeconds": 213, "isExplicit": false, "previewUrl": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview221/v4/0e/ab/8f/0eab8f87-87db-9501-110a-ad681b23ca0f/mzaf_16233060439128880755.plus.aac.p.m4a", "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/fd/4a/77/fd4a77db-0ebc-d043-41a2-f32fa1bb0fb4/dj.qrikkdwj.jpg/600x600bb.jpg", "artworkTemplate": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/fd/4a/77/fd4a77db-0ebc-d043-41a2-f32fa1bb0fb4/dj.qrikkdwj.jpg/{w}x{h}bb.jpg" } ], "artistId": "5468295", "albums": [], "singles": [], "topSongs": [], "similarArtists": [], "album": null, "about": "100 Best Albums There’s a video that Daft Punk made to promote 2001’s Discovery in which the French duo, wearing their famous robot helmets, dance on the Tokyo subway. Some riders smile and stare, while others look politely away. At the time, Daft Punk were big enough business to dismiss goofing off—their first album, 1997’s Homework, had already sold two million copies. And yet, when asked about Discovery’s turn toward ’70s and ’80s pop, Thomas Bangalter said the goal wasn’t to evoke a specific sound or era, but the raw wonder they’d felt encountering that music as children. Dancing on the subway in a city where they didn’t speak the language, liberated from judgement and self-criticism: It’s all there in the title.\n\nThe album’s biggest singles—“One More Time”, “Harder Better Faster Stronger”, “Digital Love”—were as useful to wedding DJs as they were to pop philosophers. And the rest—the faux-metal guitars of “Aerodynamic”, the sci-fi daydream of “Veridis Quo”, the UK garage showcase of Todd Edwards on “Face to Face”—glimpsed down dozens of stylistic alleyways without disrupting the album’s course. “Electronic music”—a term that always suggested the future, however vague—was demonstrated to be as familiar and comforting as classic rock, and no less real in its depth of feeling.\n\nYou can easily trace Discovery forward to EDM and the continuing entwinement of techno and rock. But you can also trace it back to The Beatles circa Sgt. Pepper’s Lonely Hearts Club Band or The Beach Boys circa Pet Sounds and Smile: music that took pop seriously as art, but also recontextualised older, seemingly uncool styles in ways that felt progressive and fresh. Most of all, though, Daft Punk wanted to be universal. And as implausible as it may have seemed for two French men in robot helmets, Discovery got them there. “We hope all the kids will love the video,” a disembodied voice says near the end of the promo clip. “As well as their parents.”", "recordLabel": "Daft Life Ltd./ADA France", "copyright": "℗ 2001 Daft Life Limited", "durationSeconds": 3668, "previewUrl": null, "motion": { "storefront": "gb", "albumId": "697194953" }, "catalogueAvailable": true, "community": { "ratingCount": 4, "averageRating": 98, "distribution": [ 0, 0, 0, 0, 4 ], "reviewCount": 2, "myRating": null, "myReview": null, "snapshot": { "title": "Discovery", "artistName": "Daft Punk", "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/fd/4a/77/fd4a77db-0ebc-d043-41a2-f32fa1bb0fb4/dj.qrikkdwj.jpg/600x600bb.jpg" } } }, "meta": { "apiVersion": 1, "migrationPhase": 3, "sourceOfTruth": "per_account" } } } } }, "400": { "description": "`type` or `id` is not a music reference Rankd understands.", "x-request": "/v1/music/album/abc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_music_reference", "message": "Not a music reference Rankd understands." } } } } }, "404": { "description": "Neither the catalogue nor Rankd knows this item.", "x-request": "/v1/music/album/999999999999", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "That music is not in the catalogue." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/music/{type}/{id}/reviews": { "get": { "operationId": "getMusicReviews", "tags": [ "Music", "Reviews" ], "summary": "Reviews of an album, song or artist", "description": "Public reviews of one catalogue item, newest first. Not paginated: it returns up to `limit` reviews.", "parameters": [ { "name": "type", "in": "path", "required": true, "description": "What kind of catalogue item.", "schema": { "type": "string", "enum": [ "album", "song", "artist" ] }, "example": "song" }, { "name": "id", "in": "path", "required": true, "description": "The Apple Music catalogue id.", "schema": { "type": "string", "pattern": "^[0-9]{1,15}$" }, "example": "1590368894" }, { "name": "limit", "in": "query", "required": false, "description": "How many items to return. Default 20, at most 50. Larger values are capped at 50; anything that is not a positive whole number gives the default.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } } ], "responses": { "200": { "description": "Public reviews.", "x-request": "/v1/music/song/1590368894/reviews?limit=5", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewCard" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "data": [ { "id": "2ea78192-78b7-49c9-80d0-893d247e4787", "username": "kyle", "displayName": "kyle", "avatarUrl": "https://api.rankdmusic.app/v1/assets/ast_9E07Q6Q598DXKRQBN0NDSCQYA4", "music": { "provider": "apple_music", "type": "song", "id": "1590368894", "title": "All Too Well (10 Minute Version) [Taylor's Version] [From The Vault]", "artistName": "Taylor Swift", "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music115/v4/15/38/9b/15389bf4-8074-06c3-11ee-655b5453af68/21UM1IM25046.rgb.jpg/600x600bb.jpg" }, "artworkTemplate": "https://is1-ssl.mzstatic.com/image/thumb/Music115/v4/15/38/9b/15389bf4-8074-06c3-11ee-655b5453af68/21UM1IM25046.rgb.jpg/{w}x{h}bb.jpg", "body": "amazing 🤩", "containsSpoilers": false, "ratingValue": 100, "createdAt": "2026-09-29T17:48:53.928Z" } ], "meta": { "apiVersion": 1, "migrationPhase": 3, "sourceOfTruth": "per_account" } } } } }, "400": { "description": "`type` or `id` is not a music reference Rankd understands.", "x-request": "/v1/music/album/abc", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_music_reference", "message": "Not a music reference Rankd understands." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/search/people": { "get": { "operationId": "searchPeople", "tags": [ "Search" ], "summary": "Search people", "description": "Finds people by username or display name: an exact username first, then usernames that start with the query, then the rest. Only people who chose to be discoverable are found.", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "At least two characters. A leading `@` is ignored.", "schema": { "type": "string", "minLength": 2 }, "example": "kyle" }, { "name": "limit", "in": "query", "required": false, "description": "How many items to return. Default 25, at most 50. Larger values are capped at 50; anything that is not a positive whole number gives the default.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } } ], "responses": { "200": { "description": "Matching people.", "x-request": "/v1/search/people?q=kyle&limit=5", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PersonResult" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "data": [ { "username": "kyle", "displayName": "kyle", "avatarUrl": "https://api.rankdmusic.app/v1/assets/ast_9E07Q6Q598DXKRQBN0NDSCQYA4", "ratingCount": 725 } ], "meta": { "apiVersion": 1, "migrationPhase": 3, "sourceOfTruth": "per_account" } } } } }, "400": { "description": "`q` is shorter than two characters.", "x-request": "/v1/music/search?q=a", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_query", "message": "Search for at least two characters." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/search/lists": { "get": { "operationId": "searchLists", "tags": [ "Search", "Lists" ], "summary": "Search lists", "description": "Finds public lists by title, description or who made them.", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "At least two characters.", "schema": { "type": "string", "minLength": 2 }, "example": "albums" }, { "name": "limit", "in": "query", "required": false, "description": "How many items to return. Default 25, at most 50. Larger values are capped at 50; anything that is not a positive whole number gives the default.", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } } ], "responses": { "200": { "description": "Matching public lists.", "x-request": "/v1/search/lists?q=albums&limit=10", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ListResult" } }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "data": [ { "id": "b218ac44-4233-4230-ae9e-ecf31ea4b5b6", "ownerUsername": "kyle", "ownerName": "kyle", "title": "Albums I Love!", "kind": "ranked", "emoji": "", "entryCount": 16, "covers": [ "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/1d/1b/f9/1d1bf9b1-44c6-9a6c-6ffb-c158488c06ce/26UMGIM39303.rgb.jpg/{w}x{h}bb.jpg", "https://is1-ssl.mzstatic.com/image/thumb/Music125/v4/37/ae/95/37ae95a0-2e1c-bf03-4900-983686da9292/12UMGIM00033.rgb.jpg/{w}x{h}bb.jpg" ], "updatedAt": "2026-07-23T14:19:54.728Z" }, { "id": "1082404f-6402-437b-a137-89b585754d74", "ownerUsername": "kyle", "ownerName": "kyle", "title": "My 5★ Albums", "kind": "collection", "emoji": "🌟", "entryCount": 14, "covers": [ "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/58/8f/a9/588fa9a2-7cc5-f02c-9ce6-c986e0dc1c15/25UM1IM19577.rgb.jpg/{w}x{h}bb.jpg", "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/eb/e6/06/ebe606da-e00f-82d3-47f3-b79904eed541/17UM1IM24651.rgb.jpg/{w}x{h}bb.jpg" ], "updatedAt": "2026-09-29T13:15:54.311Z" } ], "meta": { "apiVersion": 1, "migrationPhase": 3, "sourceOfTruth": "per_account" } } } } }, "400": { "description": "`q` is shorter than two characters.", "x-request": "/v1/music/search?q=a", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_query", "message": "Search for at least two characters." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/users/by-username/{username}": { "get": { "operationId": "getUserByUsername", "tags": [ "Users" ], "summary": "Look up a user by username", "description": "The user behind a username: how to get from a Rankd username to a user id. Only discoverable people are found.", "parameters": [ { "name": "username", "in": "path", "required": true, "description": "A Rankd username: up to 20 letters, digits and underscores. Case does not matter.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9_]{1,20}$" }, "example": "kyle" } ], "responses": { "200": { "description": "The user.", "x-request": "/v1/users/by-username/kyle", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/User" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "data": { "id": "usr_01KY0JGXMWTT8H9WFN9RTM5JP9", "username": "kyle", "displayName": "kyle", "bio": "🏴󠁧󠁢󠁳󠁣󠁴󠁿", "foundingMember": { "number": 2, "grantedAt": "2026-09-17T14:44:05.000Z" }, "avatarAssetId": "ast_9E07Q6Q598DXKRQBN0NDSCQYA4", "avatarUrl": "https://api.rankdmusic.app/v1/assets/ast_9E07Q6Q598DXKRQBN0NDSCQYA4", "isDiscoverable": true, "createdAt": "2026-07-20T20:12:20.508Z", "updatedAt": "2026-09-29T11:24:06.862Z" }, "meta": { "apiVersion": 1, "migrationPhase": 3, "sourceOfTruth": "per_account" } } } } }, "400": { "description": "Not something a Rankd username can be.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_username", "message": "Invalid username." } } } } }, "404": { "description": "No such user, or they are not discoverable.", "x-request": "/v1/users/by-username/no_such_person_zz", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "User not found." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/users/{userId}": { "get": { "operationId": "getUser", "tags": [ "Users" ], "summary": "Get a profile", "description": "A whole profile in one request: the user, their public counts, the music pinned to their profile and their achievements.", "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "A Rankd user id: `usr_` then 26 characters. Get one from **Look up a user by username**.", "schema": { "type": "string", "pattern": "^usr_[0-9A-Z]{26}$" }, "example": "usr_01KY0JGXMWTT8H9WFN9RTM5JP9" } ], "responses": { "200": { "description": "The profile.", "x-request": "/v1/users/usr_01KY0JGXMWTT8H9WFN9RTM5JP9", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/UserProfile" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "data": { "id": "usr_01KY0JGXMWTT8H9WFN9RTM5JP9", "username": "kyle", "displayName": "kyle", "bio": "🏴󠁧󠁢󠁳󠁣󠁴󠁿", "foundingMember": { "number": 2, "grantedAt": "2026-09-17T14:44:05.000Z" }, "avatarAssetId": "ast_9E07Q6Q598DXKRQBN0NDSCQYA4", "avatarUrl": "https://api.rankdmusic.app/v1/assets/ast_9E07Q6Q598DXKRQBN0NDSCQYA4", "isDiscoverable": true, "createdAt": "2026-07-20T20:12:20.508Z", "updatedAt": "2026-09-29T11:24:06.862Z", "stats": { "ratings": 725, "reviews": 5, "lists": 7, "followers": 4, "following": 4 }, "pins": [ { "slot": "album", "position": 0, "music": { "provider": "apple_music", "type": "album", "id": "1742057774", "title": "THE TORTURED POETS DEPARTMENT: THE ANTHOLOGY", "artistName": "Taylor Swift", "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/a4/86/59/a486593a-53c9-1c2a-5122-8f25339f7359/24UMGIM44778.rgb.jpg/600x600bb.jpg" }, "artworkTemplate": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/a4/86/59/a486593a-53c9-1c2a-5122-8f25339f7359/24UMGIM44778.rgb.jpg/{w}x{h}bb.jpg" }, { "slot": "artist", "position": 0, "music": { "provider": "apple_music", "type": "artist", "id": "159260351", "title": "Taylor Swift", "artistName": "", "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a700799-2026-09-25T04-00-05.358Z_cropped.png/600x600bb.jpg" }, "artworkTemplate": "https://is1-ssl.mzstatic.com/image/thumb/AMCArtistImages221/v4/6d/67/88/6d67888b-9e7f-53af-7853-0f91d6fd2332/ami_U003aidentity_U003a994af5c375f4c3aa96cd6ced4a700799-2026-09-25T04-00-05.358Z_cropped.png/{w}x{h}bb.jpg" } ], "achievements": [ { "id": "artists-10", "unlockedAt": "2026-09-19T22:02:30.416Z" }, { "id": "songs-500", "unlockedAt": "2026-09-14T21:44:50.564Z" } ] }, "meta": { "apiVersion": 1, "migrationPhase": 3, "sourceOfTruth": "per_account" } } } } }, "404": { "description": "No such user, or they are not discoverable.", "x-request": "/v1/users/by-username/no_such_person_zz", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "User not found." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/users/{userId}/ratings": { "get": { "operationId": "listUserRatings", "tags": [ "Users" ], "summary": "A user’s ratings", "description": "Their public ratings, most recently changed first. A rating is a whole number from 0 to 100.", "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "A Rankd user id: `usr_` then 26 characters. Get one from **Look up a user by username**.", "schema": { "type": "string", "pattern": "^usr_[0-9A-Z]{26}$" }, "example": "usr_01KY0JGXMWTT8H9WFN9RTM5JP9" }, { "name": "limit", "in": "query", "required": false, "description": "How many items to return. Default 30, at most 100. Larger values are capped at 100; anything that is not a positive whole number gives the default.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.nextCursor` of the previous page. Leave it out for the first page. Cursors are opaque: pass them back unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of ratings.", "x-request": "/v1/users/usr_01KY0JGXMWTT8H9WFN9RTM5JP9/ratings?limit=2", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Rating" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "data": [ { "id": "rat_01M3QSX2M2ESSG165BGJWYM5ZS", "music": { "provider": "apple_music", "type": "song", "id": "697195462", "title": "One More Time", "artistName": "Daft Punk", "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/fd/4a/77/fd4a77db-0ebc-d043-41a2-f32fa1bb0fb4/dj.qrikkdwj.jpg/600x600bb.jpg", "albumId": "697194953", "albumTitle": "Discovery" }, "value": 80, "visibility": "public", "createdAt": "2026-09-30T00:02:19.906Z", "createdAtPrecision": "exact", "updatedAt": "2026-09-30T00:02:19.906Z" }, { "id": "rat_01M3EZRBAW621QVN73BHKENP8B", "music": { "provider": "apple_music", "type": "song", "id": "6814997428", "title": "Pink Clouding", "artistName": "Taylor Swift", "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/a0/dd/fd/a0ddfd72-ee9e-f046-6466-a5dbefc696fa/26UM1IM21436.rgb.jpg/600x600bb.jpg", "albumId": "6814997249", "albumTitle": "The Life of a Showgirl: The Encore" }, "value": 100, "visibility": null, "createdAt": "2026-09-26T13:51:26.556Z", "createdAtPrecision": "exact", "updatedAt": "2026-09-29T23:40:53.152Z" } ], "meta": { "apiVersion": 1, "migrationPhase": 3, "sourceOfTruth": "per_account", "nextCursor": "MTc5MDcyNTI1MzE1MnxyYXRfMDFNM0VaUkJBVzYyMVFWTjczQkhLRU5QOEI" } } } } }, "404": { "description": "No such user, or they are not discoverable.", "x-request": "/v1/users/by-username/no_such_person_zz", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "User not found." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/users/{userId}/reviews": { "get": { "operationId": "listUserReviews", "tags": [ "Users", "Reviews" ], "summary": "A user’s reviews", "description": "Their public reviews, newest first.", "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "A Rankd user id: `usr_` then 26 characters. Get one from **Look up a user by username**.", "schema": { "type": "string", "pattern": "^usr_[0-9A-Z]{26}$" }, "example": "usr_01KY0JGXMWTT8H9WFN9RTM5JP9" }, { "name": "limit", "in": "query", "required": false, "description": "How many items to return. Default 30, at most 100. Larger values are capped at 100; anything that is not a positive whole number gives the default.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.nextCursor` of the previous page. Leave it out for the first page. Cursors are opaque: pass them back unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of reviews.", "x-request": "/v1/users/usr_01KY0JGXMWTT8H9WFN9RTM5JP9/reviews?limit=2", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Review" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "data": [ { "id": "2ea78192-78b7-49c9-80d0-893d247e4787", "userId": "usr_01KY0JGXMWTT8H9WFN9RTM5JP9", "username": "kyle", "music": { "provider": "apple_music", "type": "song", "id": "1590368894", "title": "All Too Well (10 Minute Version) [Taylor's Version] [From The Vault]", "artistName": "Taylor Swift", "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music115/v4/15/38/9b/15389bf4-8074-06c3-11ee-655b5453af68/21UM1IM25046.rgb.jpg/600x600bb.jpg", "albumId": "1590368448", "albumTitle": "Red (Taylor’s Version) [+ A Message from Taylor]" }, "body": "amazing 🤩", "containsSpoilers": false, "ratingValue": 100, "visibility": "public", "createdAt": "2026-09-29T17:48:53.928Z", "updatedAt": "2026-09-29T17:48:53.928Z" }, { "id": "5e8e7447-a3d0-4cd0-86a3-f5849df4a9f7", "userId": "usr_01KY0JGXMWTT8H9WFN9RTM5JP9", "username": "kyle", "music": { "provider": "apple_music", "type": "song", "id": "570216128", "title": "Real Gone Kid", "artistName": "Deacon Blue", "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music/v4/2b/ec/6c/2bec6ca0-fee4-d425-d4cf-b6b3d786b0f2/886443693197.jpg/600x600bb.jpg", "albumId": null, "albumTitle": null }, "body": "Unreal song", "containsSpoilers": false, "ratingValue": 100, "visibility": "public", "createdAt": "2026-09-12T09:43:23.142Z", "updatedAt": "2026-09-28T17:27:40.767Z" } ], "meta": { "apiVersion": 1, "migrationPhase": 3, "sourceOfTruth": "per_account", "nextCursor": "MTc4OTIwNjIwMzE0Mnw1ZThlNzQ0Ny1hM2QwLTRjZDAtODZhMy1mNTg0OWRmNGE5Zjc" } } } } }, "404": { "description": "No such user, or they are not discoverable.", "x-request": "/v1/users/by-username/no_such_person_zz", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "User not found." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/users/{userId}/lists": { "get": { "operationId": "listUserLists", "tags": [ "Users", "Lists" ], "summary": "A user’s lists", "description": "Their public lists, most recently updated first.", "parameters": [ { "name": "userId", "in": "path", "required": true, "description": "A Rankd user id: `usr_` then 26 characters. Get one from **Look up a user by username**.", "schema": { "type": "string", "pattern": "^usr_[0-9A-Z]{26}$" }, "example": "usr_01KY0JGXMWTT8H9WFN9RTM5JP9" }, { "name": "limit", "in": "query", "required": false, "description": "How many items to return. Default 30, at most 100. Larger values are capped at 100; anything that is not a positive whole number gives the default.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `meta.nextCursor` of the previous page. Leave it out for the first page. Cursors are opaque: pass them back unchanged.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of lists.", "x-request": "/v1/users/usr_01KY0JGXMWTT8H9WFN9RTM5JP9/lists?limit=2", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ListSummary" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "data": [ { "id": "9c56fe92-4ac1-463d-af4b-bbadfd11e5eb", "title": "Songs I don’t rate", "kind": "smart", "visibility": "public", "emoji": "", "entryCount": 0, "updatedAt": "2026-09-29T20:36:57.231Z" }, { "id": "1082404f-6402-437b-a137-89b585754d74", "title": "My 5★ Albums", "kind": "collection", "visibility": "public", "emoji": "🌟", "entryCount": 14, "updatedAt": "2026-09-29T13:15:54.311Z" } ], "meta": { "apiVersion": 1, "migrationPhase": 3, "sourceOfTruth": "per_account", "nextCursor": "MTc5MDY4Nzc1NDMxMXwxMDgyNDA0Zi02NDAyLTQzN2ItYTEzNy04OWI1ODU3NTRkNzQ" } } } } }, "404": { "description": "No such user, or they are not discoverable.", "x-request": "/v1/users/by-username/no_such_person_zz", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "User not found." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/lists/{listId}": { "get": { "operationId": "getList", "tags": [ "Lists" ], "summary": "Get a list", "description": "A public list with its entries in order (up to 500).", "parameters": [ { "name": "listId", "in": "path", "required": true, "description": "The list’s id, a UUID.", "schema": { "type": "string", "pattern": "^[0-9a-f-]{36}$" }, "example": "1082404f-6402-437b-a137-89b585754d74" }, { "name": "owner", "in": "query", "required": false, "description": "The owner’s username. Rankd share links include it. It picks the right list when the id is one the app gave the list and more than one person has a list with that id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The list.", "x-request": "/v1/lists/1082404f-6402-437b-a137-89b585754d74", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/List" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "data": { "id": "1082404f-6402-437b-a137-89b585754d74", "clientId": "1082404f-6402-437b-a137-89b585754d74", "ownerUserId": "usr_01KY0JGXMWTT8H9WFN9RTM5JP9", "ownerUsername": "kyle", "title": "My 5★ Albums", "description": "", "kind": "collection", "visibility": "public", "emoji": "🌟", "icon": "wand.and.stars", "theme": "gold", "category": "", "tags": [], "createdAt": "2026-07-23T20:36:17.877Z", "updatedAt": "2026-09-29T13:15:54.311Z", "entries": [ { "position": 0, "note": "", "music": { "provider": "apple_music", "type": "album", "id": "1838810949", "title": "The Life of a Showgirl", "artistName": "Taylor Swift", "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/58/8f/a9/588fa9a2-7cc5-f02c-9ce6-c986e0dc1c15/25UM1IM19577.rgb.jpg/600x600bb.jpg", "albumId": null, "albumTitle": null } }, { "position": 1, "note": "", "music": { "provider": "apple_music", "type": "album", "id": "1440933849", "title": "reputation", "artistName": "Taylor Swift", "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/eb/e6/06/ebe606da-e00f-82d3-47f3-b79904eed541/17UM1IM24651.rgb.jpg/600x600bb.jpg", "albumId": null, "albumTitle": null } } ] }, "meta": { "apiVersion": 1, "migrationPhase": 3, "sourceOfTruth": "per_account" } } } } }, "404": { "description": "No such list, or it is private.", "x-request": "/v1/lists/00000000-0000-0000-0000-000000000000", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "List not found." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/reviews/{reviewId}": { "get": { "operationId": "getReview", "tags": [ "Reviews" ], "summary": "Get a review", "description": "One public review.", "parameters": [ { "name": "reviewId", "in": "path", "required": true, "description": "The review’s id, a UUID.", "schema": { "type": "string", "pattern": "^[0-9a-f-]{36}$" }, "example": "2ea78192-78b7-49c9-80d0-893d247e4787" } ], "responses": { "200": { "description": "The review.", "x-request": "/v1/reviews/2ea78192-78b7-49c9-80d0-893d247e4787", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Review" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ], "additionalProperties": false }, "example": { "data": { "id": "2ea78192-78b7-49c9-80d0-893d247e4787", "userId": "usr_01KY0JGXMWTT8H9WFN9RTM5JP9", "username": "kyle", "music": { "provider": "apple_music", "type": "song", "id": "1590368894", "title": "All Too Well (10 Minute Version) [Taylor's Version] [From The Vault]", "artistName": "Taylor Swift", "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music115/v4/15/38/9b/15389bf4-8074-06c3-11ee-655b5453af68/21UM1IM25046.rgb.jpg/600x600bb.jpg", "albumId": "1590368448", "albumTitle": "Red (Taylor’s Version) [+ A Message from Taylor]" }, "body": "amazing 🤩", "containsSpoilers": false, "ratingValue": 100, "visibility": "public", "createdAt": "2026-09-29T17:48:53.928Z", "updatedAt": "2026-09-29T17:48:53.928Z" }, "meta": { "apiVersion": 1, "migrationPhase": 3, "sourceOfTruth": "per_account" } } } } }, "404": { "description": "No such review, or it is not public.", "x-request": "/v1/reviews/00000000-0000-0000-0000-000000000000", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Review not found." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/assets/{assetId}": { "get": { "operationId": "getAsset", "tags": [ "Assets" ], "summary": "Get an image", "description": "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.", "x-binary": true, "parameters": [ { "name": "assetId", "in": "path", "required": true, "description": "`ast_` then 26 characters.", "schema": { "type": "string", "pattern": "^ast_[0-9A-Z]{26}$" }, "example": "ast_9E07Q6Q598DXKRQBN0NDSCQYA4" }, { "name": "If-None-Match", "in": "header", "required": false, "description": "The `ETag` of a copy you already have.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The image. `Content-Type` is the image’s own type, such as `image/jpeg`.", "headers": { "ETag": { "description": "A fingerprint of the image.", "schema": { "type": "string" } }, "Cache-Control": { "description": "Always `public, max-age=3600`.", "schema": { "type": "string" } } }, "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "304": { "description": "The copy you have (from `If-None-Match`) is current." }, "404": { "description": "No such image, or what showed it is no longer public.", "x-request": "/v1/assets/ast_00000000000000000000000000", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "Asset not found." } } } } } } } } }, "components": { "responses": { "RateLimited": { "description": "Too many requests this minute. Wait `Retry-After` seconds, then try again.", "headers": { "Retry-After": { "description": "Seconds to wait. Always `60`.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitError" }, "example": { "error": "rate limited" } } } }, "Unauthenticated": { "description": "The endpoint needs a Rankd account.", "x-request": "/v1/me", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthenticated", "message": "A Rankd session or operator token is required." } } } } } }, "schemas": { "Meta": { "type": "object", "properties": { "apiVersion": { "type": "integer", "description": "The API version that answered." }, "migrationPhase": { "type": "integer", "description": "Internal to Rankd. Ignore it." }, "sourceOfTruth": { "type": "string", "description": "Internal to Rankd. Ignore it." } }, "required": [ "apiVersion" ], "additionalProperties": false, "description": "Sent with every successful JSON response." }, "PageMeta": { "type": "object", "properties": { "apiVersion": { "type": "integer", "description": "The API version that answered." }, "migrationPhase": { "type": "integer", "description": "Internal to Rankd. Ignore it." }, "sourceOfTruth": { "type": "string", "description": "Internal to Rankd. Ignore it." }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass this as `cursor` to get the next page. `null` or missing on the last page." } }, "required": [ "apiVersion" ], "additionalProperties": false, "description": "`Meta`, plus the cursor for the next page." }, "FeedMeta": { "type": "object", "properties": { "apiVersion": { "type": "integer", "description": "The API version that answered." }, "migrationPhase": { "type": "integer", "description": "Internal to Rankd. Ignore it." }, "sourceOfTruth": { "type": "string", "description": "Internal to Rankd. Ignore it." }, "nextCursor": { "type": [ "string", "null" ], "description": "Pass this as `cursor` for the next page. `null` at the end." }, "personalized": { "type": "boolean", "description": "Whether the feed is shaped by the caller’s own taste. Always `false` without credentials." }, "coldStart": { "type": "boolean", "description": "Whether this is the general community ranking rather than a feed shaped by who the caller follows." } }, "required": [ "apiVersion" ], "additionalProperties": false, "description": "`Meta` for the feed." }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A stable, machine-readable reason. Branch on this." }, "message": { "type": "string", "description": "A readable explanation. Its wording can change, so do not parse it." } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false, "description": "Every error except rate limiting." }, "RateLimitError": { "type": "object", "properties": { "error": { "type": "string", "description": "Always `rate limited`.", "enum": [ "rate limited" ] } }, "required": [ "error" ], "additionalProperties": false, "description": "The rate limiter answers before the API does, so this body is shaped differently from other errors." }, "ApiInfo": { "type": "object", "properties": { "name": { "type": "string", "description": "The API’s name." }, "version": { "type": "integer", "description": "The API version." }, "documentation": { "type": "string", "description": "A pointer to Rankd’s internal notes. Use this site instead." } }, "required": [ "name", "version" ], "additionalProperties": false }, "Health": { "type": "object", "properties": { "database": { "type": "string", "description": "Whether the API could query its database.", "enum": [ "ok", "error" ] } }, "required": [ "database" ], "additionalProperties": false }, "MusicRef": { "type": "object", "properties": { "provider": { "type": "string", "description": "The catalogue the id belongs to.", "enum": [ "apple_music" ] }, "type": { "type": "string", "description": "What kind of item.", "enum": [ "album", "song", "artist", "music_video" ] }, "id": { "type": "string", "description": "The catalogue id." }, "title": { "type": [ "string", "null" ], "description": "The title when Rankd stored it." }, "artistName": { "type": [ "string", "null" ], "description": "The artist when Rankd stored it. Empty for artists." }, "artworkUrl": { "type": [ "string", "null" ], "description": "Artwork at 600×600 on Apple’s image servers." }, "albumId": { "type": [ "string", "null" ], "description": "For songs: the album it is from." }, "albumTitle": { "type": [ "string", "null" ], "description": "For songs: that album’s title." } }, "required": [ "provider", "type", "id" ], "additionalProperties": false, "description": "A piece of music as Rankd stores it: a catalogue reference plus the title and artwork it had when it was saved." }, "MusicSummary": { "type": "object", "properties": { "provider": { "type": "string", "description": "The catalogue the id belongs to.", "enum": [ "apple_music" ] }, "type": { "type": "string", "description": "What kind of item.", "enum": [ "album", "song", "artist", "music_video" ] }, "id": { "type": "string", "description": "The catalogue id." }, "title": { "type": [ "string", "null" ], "description": "Title." }, "artistName": { "type": [ "string", "null" ], "description": "Artist. Empty or `null` for artists." }, "artworkUrl": { "type": [ "string", "null" ], "description": "Artwork at 600×600." }, "artworkTemplate": { "type": [ "string", "null" ], "description": "Artwork with `{w}x{h}` in place of the size, so you can ask for exactly the size you draw." }, "releaseYear": { "type": [ "integer", "null" ], "description": "Year of release, where known." }, "albumId": { "type": [ "string", "null" ], "description": "For songs: their album’s id." }, "albumTitle": { "type": [ "string", "null" ], "description": "For songs: their album." }, "trackNumber": { "type": [ "integer", "null" ], "description": "For tracks: position on the disc." }, "discNumber": { "type": [ "integer", "null" ], "description": "For tracks: which disc." }, "durationSeconds": { "type": [ "integer", "null" ], "description": "For tracks: length in seconds." }, "isExplicit": { "type": "boolean", "description": "For tracks: marked explicit." }, "previewUrl": { "type": [ "string", "null" ], "description": "For tracks: Apple’s 30-second preview." }, "isSingle": { "type": "boolean", "description": "For albums: Apple lists it as a single or EP." }, "genre": { "type": [ "string", "null" ], "description": "Primary genre." } }, "required": [ "type", "id" ], "additionalProperties": false, "description": "A catalogue item as it appears in results, charts and tracklists. Which fields are present depends on where it appears." }, "MusicSearchResults": { "type": "object", "properties": { "album": { "type": "array", "items": { "$ref": "#/components/schemas/MusicSummary" } }, "artist": { "type": "array", "items": { "$ref": "#/components/schemas/MusicSummary" } }, "song": { "type": "array", "items": { "$ref": "#/components/schemas/MusicSummary" } } }, "required": [], "additionalProperties": false, "description": "One key for each type you asked for." }, "Community": { "type": "object", "properties": { "ratingCount": { "type": "integer", "description": "How many people rated it publicly." }, "averageRating": { "type": [ "number", "null" ], "description": "Average rating, 0–100. `null` with no ratings." }, "distribution": { "type": "array", "items": { "type": "integer" }, "description": "How many ratings fall in each fifth of the scale, lowest first." }, "reviewCount": { "type": "integer", "description": "How many public reviews it has." }, "myRating": { "type": [ "object", "null" ], "description": "The caller’s own rating. Always `null` without credentials." }, "myReview": { "type": [ "object", "null" ], "description": "The caller’s own review. Always `null` without credentials." }, "snapshot": { "type": [ "object", "null" ], "description": "The title and artwork Rankd stored, for when the catalogue has nothing.", "additionalProperties": true } }, "required": [ "ratingCount", "distribution", "reviewCount" ], "additionalProperties": false, "description": "What the Rankd community makes of an item. Private ratings never count." }, "MusicItem": { "type": "object", "properties": { "music": { "$ref": "#/components/schemas/MusicRef" }, "artworkTemplate": { "type": [ "string", "null" ], "description": "Artwork with `{w}x{h}` in place of the size." }, "releaseDate": { "type": [ "string", "null" ], "description": "Release date, `YYYY-MM-DD`." }, "releaseYear": { "type": [ "integer", "null" ], "description": "Release year." }, "genreNames": { "type": "array", "items": { "type": "string" }, "description": "Apple’s genres." }, "trackCount": { "type": [ "integer", "null" ], "description": "For albums: how many tracks." }, "tracks": { "type": "array", "items": { "$ref": "#/components/schemas/MusicSummary" }, "description": "For albums: the tracklist." }, "artistId": { "type": [ "string", "null" ], "description": "For albums and songs: the lead artist’s id." }, "albums": { "type": "array", "items": { "$ref": "#/components/schemas/MusicSummary" }, "description": "For artists: their albums." }, "singles": { "type": "array", "items": { "$ref": "#/components/schemas/MusicSummary" }, "description": "For artists: their singles and EPs." }, "topSongs": { "type": "array", "items": { "$ref": "#/components/schemas/MusicSummary" }, "description": "For artists: their most popular songs." }, "similarArtists": { "type": "array", "items": { "$ref": "#/components/schemas/MusicSummary" }, "description": "For artists: artists like them." }, "album": { "oneOf": [ { "$ref": "#/components/schemas/MusicSummary" }, { "type": "null" } ], "description": "For songs: the album they are from." }, "about": { "type": [ "string", "null" ], "description": "Apple’s editorial notes, as plain text." }, "recordLabel": { "type": [ "string", "null" ], "description": "For albums: the label." }, "copyright": { "type": [ "string", "null" ], "description": "For albums: the copyright line." }, "durationSeconds": { "type": [ "integer", "null" ], "description": "Length in seconds." }, "previewUrl": { "type": [ "string", "null" ], "description": "For songs: Apple’s 30-second preview." }, "motion": { "type": [ "object", "null" ], "description": "Where Rankd’s apps look for the album’s animated cover.", "properties": { "storefront": { "type": "string", "description": "Apple Music storefront." }, "albumId": { "type": "string", "description": "Album id." } }, "additionalProperties": false }, "catalogueAvailable": { "type": "boolean", "description": "Whether Apple Music answered. When `false`, only the details Rankd stored are shown." }, "community": { "$ref": "#/components/schemas/Community" } }, "required": [ "music", "community", "catalogueAvailable" ], "additionalProperties": false }, "FoundingMember": { "type": [ "object", "null" ], "description": "Set when the person is one of Rankd’s Founding Members.", "properties": { "number": { "type": "integer", "description": "Their Founding Member number." }, "grantedAt": { "type": "string", "format": "date-time", "description": "When it was granted." } }, "additionalProperties": false }, "User": { "type": "object", "properties": { "id": { "type": "string", "description": "The user’s id." }, "username": { "type": "string", "description": "Their username." }, "displayName": { "type": [ "string", "null" ], "description": "The name they show." }, "bio": { "type": [ "string", "null" ], "description": "Their bio." }, "foundingMember": { "$ref": "#/components/schemas/FoundingMember" }, "avatarAssetId": { "type": [ "string", "null" ], "description": "Their profile picture, as an asset id." }, "avatarUrl": { "type": [ "string", "null" ], "description": "Their profile picture’s URL." }, "isDiscoverable": { "type": "boolean", "description": "Whether people who are not signed in can find them." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When they joined." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When their profile last changed." } }, "required": [ "id", "username" ], "additionalProperties": false }, "UserProfile": { "description": "`User`, plus the rest of the profile.", "allOf": [ { "$ref": "#/components/schemas/User" }, { "type": "object", "properties": { "stats": { "type": "object", "properties": { "ratings": { "type": "integer", "description": "Ratings." }, "reviews": { "type": "integer", "description": "Reviews." }, "lists": { "type": "integer", "description": "Lists." }, "followers": { "type": "integer", "description": "Followers." }, "following": { "type": "integer", "description": "Following." } }, "required": [], "additionalProperties": false, "description": "Public counts." }, "pins": { "type": "array", "items": { "type": "object", "properties": { "slot": { "type": "string", "description": "Which favourite slot.", "enum": [ "album", "artist", "song" ] }, "position": { "type": "integer", "description": "Order within the slot." }, "music": { "$ref": "#/components/schemas/MusicRef" }, "artworkTemplate": { "type": [ "string", "null" ], "description": "Artwork with `{w}x{h}`." } }, "required": [], "additionalProperties": false }, "description": "Music pinned to their profile." }, "achievements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Which achievement." }, "unlockedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was unlocked." } }, "required": [], "additionalProperties": false }, "description": "Achievements they have unlocked." } } } ] }, "Rating": { "type": "object", "properties": { "id": { "type": "string", "description": "The rating’s id." }, "music": { "$ref": "#/components/schemas/MusicRef" }, "value": { "type": "integer", "description": "The rating, 0–100. Rankd’s apps show it as stars (value ÷ 20) or as a score out of 100.", "minimum": 0, "maximum": 100 }, "visibility": { "type": [ "string", "null" ], "enum": [ "public", null ], "description": "`public`, or `null` for ratings made before Rankd had visibility settings (those are public too)." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was made." }, "createdAtPrecision": { "type": "string", "description": "`approximate` for ratings imported without an exact time.", "enum": [ "exact", "approximate" ] }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When it last changed." } }, "required": [ "id", "music", "value" ], "additionalProperties": false }, "Review": { "type": "object", "properties": { "id": { "type": "string", "description": "The review’s id." }, "userId": { "type": "string", "description": "Who wrote it." }, "username": { "type": "string", "description": "Their username." }, "music": { "$ref": "#/components/schemas/MusicRef" }, "body": { "type": "string", "description": "The review." }, "containsSpoilers": { "type": "boolean", "description": "The author marked it as containing spoilers." }, "ratingValue": { "type": [ "integer", "null" ], "description": "The rating given with it, 0–100." }, "visibility": { "type": "string", "description": "Always `public` without credentials." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was written." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When it last changed." } }, "required": [ "id", "username", "body" ], "additionalProperties": false }, "ReviewCard": { "type": "object", "properties": { "id": { "type": "string", "description": "The review’s id." }, "username": { "type": "string", "description": "The author." }, "displayName": { "type": [ "string", "null" ], "description": "The author’s display name." }, "avatarUrl": { "type": [ "string", "null" ], "description": "The author’s profile picture." }, "music": { "$ref": "#/components/schemas/MusicRef" }, "artworkTemplate": { "type": [ "string", "null" ], "description": "Artwork with `{w}x{h}`." }, "body": { "type": "string", "description": "The review." }, "containsSpoilers": { "type": "boolean", "description": "Marked as containing spoilers." }, "ratingValue": { "type": [ "integer", "null" ], "description": "The rating given with it, 0–100." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was written." } }, "required": [ "id", "username", "body" ], "additionalProperties": false, "description": "A review with its author, as music pages and Discover show it." }, "ListSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "The list’s id." }, "title": { "type": "string", "description": "Title." }, "kind": { "type": "string", "description": "`ranked` lists are in order, `collection`s are not, `smart` lists fill themselves.", "enum": [ "ranked", "collection", "smart", "collaborative" ] }, "visibility": { "type": "string", "description": "Always `public` without credentials." }, "emoji": { "type": [ "string", "null" ], "description": "Its emoji. May be empty." }, "entryCount": { "type": "integer", "description": "How many entries." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When it last changed." } }, "required": [ "id", "title" ], "additionalProperties": false }, "ListResult": { "type": "object", "properties": { "id": { "type": "string", "description": "The list’s id." }, "ownerUsername": { "type": "string", "description": "Who made it." }, "ownerName": { "type": [ "string", "null" ], "description": "Their display name." }, "title": { "type": "string", "description": "Title." }, "kind": { "type": "string", "description": "`ranked`, `collection`, `smart` or `collaborative`." }, "emoji": { "type": [ "string", "null" ], "description": "Its emoji. May be empty." }, "entryCount": { "type": "integer", "description": "How many entries." }, "covers": { "type": "array", "items": { "type": "string" }, "description": "Artwork templates (`{w}x{h}`) of its first entries." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When it last changed." } }, "required": [ "id", "title" ], "additionalProperties": false }, "List": { "type": "object", "properties": { "id": { "type": "string", "description": "The list’s id." }, "clientId": { "type": [ "string", "null" ], "description": "The id the app gave it. Usually the same as `id`." }, "ownerUserId": { "type": "string", "description": "Who made it." }, "ownerUsername": { "type": "string", "description": "Their username." }, "title": { "type": "string", "description": "Title." }, "description": { "type": [ "string", "null" ], "description": "Description." }, "kind": { "type": "string", "description": "`ranked`, `collection`, `smart` or `collaborative`.", "enum": [ "ranked", "collection", "smart", "collaborative" ] }, "visibility": { "type": "string", "description": "Always `public` without credentials." }, "emoji": { "type": [ "string", "null" ], "description": "Emoji. May be empty." }, "icon": { "type": [ "string", "null" ], "description": "The SF Symbol name Rankd’s apps draw for it." }, "theme": { "type": [ "string", "null" ], "description": "The colour theme Rankd’s apps draw it in." }, "category": { "type": [ "string", "null" ], "description": "Category. May be empty." }, "tags": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Created." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last changed." }, "entries": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer", "description": "Position, from 0." }, "note": { "type": [ "string", "null" ], "description": "The owner’s note on this entry." }, "music": { "$ref": "#/components/schemas/MusicRef" } }, "required": [], "additionalProperties": false }, "description": "In order." } }, "required": [ "id", "title", "entries" ], "additionalProperties": false }, "PersonResult": { "type": "object", "properties": { "username": { "type": "string", "description": "Username." }, "displayName": { "type": "string", "description": "Display name, or the username when they have none." }, "avatarUrl": { "type": [ "string", "null" ], "description": "Profile picture." }, "ratingCount": { "type": "integer", "description": "How many ratings they have made." } }, "required": [ "username" ], "additionalProperties": false }, "Chart": { "type": "object", "properties": { "type": { "type": "string", "description": "What is charted.", "enum": [ "album", "song", "artist", "music_video" ] }, "window": { "type": "string", "description": "The period ranked.", "enum": [ "week" ] }, "generatedAt": { "type": "string", "format": "date-time", "description": "When the chart was worked out." }, "entries": { "type": "array", "items": { "type": "object", "properties": { "rank": { "type": "integer", "description": "This week’s position." }, "previousRank": { "type": [ "integer", "null" ], "description": "Last week’s position. `null` when new." }, "movement": { "type": "string", "description": "Which way it moved.", "enum": [ "up", "down", "same", "new" ] }, "change": { "type": [ "integer", "null" ], "description": "How many places it moved." }, "music": { "$ref": "#/components/schemas/MusicSummary" }, "community": { "type": "object", "properties": { "average": { "type": "number", "description": "Average rating, 0–100." }, "count": { "type": "integer", "description": "How many ratings." } }, "required": [], "additionalProperties": false }, "rankedThisWeek": { "type": "integer", "description": "Ratings made this week." } }, "required": [], "additionalProperties": false } } }, "required": [ "type", "window", "entries" ], "additionalProperties": false }, "Discover": { "type": "object", "properties": { "trendingAlbums": { "type": "array", "items": { "type": "object", "properties": { "music": { "$ref": "#/components/schemas/MusicRef" }, "artworkTemplate": { "type": [ "string", "null" ], "description": "Artwork with `{w}x{h}`." }, "ratingCount": { "type": "integer", "description": "Ratings." }, "averageRating": { "type": [ "number", "null" ], "description": "Average, 0–100." } }, "required": [], "additionalProperties": false } }, "recentReviews": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewCard" } }, "recentLists": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "List id." }, "ownerUsername": { "type": "string", "description": "Owner." }, "ownerDisplayName": { "type": [ "string", "null" ], "description": "Owner’s display name." }, "title": { "type": "string", "description": "Title." }, "description": { "type": [ "string", "null" ], "description": "Description." }, "emoji": { "type": [ "string", "null" ], "description": "Emoji. May be empty." }, "entryCount": { "type": "integer", "description": "Entries." }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Last changed." } }, "required": [], "additionalProperties": false } }, "activeMembers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "User id." }, "username": { "type": "string", "description": "Username." }, "displayName": { "type": [ "string", "null" ], "description": "Display name." }, "avatarUrl": { "type": [ "string", "null" ], "description": "Profile picture." }, "foundingMember": { "type": [ "object", "null" ], "properties": { "number": { "type": "integer", "description": "Founding Member number." } }, "additionalProperties": false }, "ratingCount": { "type": "integer", "description": "Ratings." } }, "required": [], "additionalProperties": false } } }, "required": [], "additionalProperties": false }, "FeedCard": { "type": "object", "description": "One card in the feed. `type` says what it is and which other fields it has. Skip types you do not recognise.", "required": [ "id", "type" ], "additionalProperties": true, "properties": { "id": { "type": "string", "description": "The card’s stable id." }, "type": { "type": "string", "description": "What kind of card. Today: `rating`, `review`, `list`, `trending`, `new_release`, `insight` and `suggested_users`. More can be added." }, "createdAt": { "type": [ "string", "null" ], "format": "date-time", "description": "When the thing it shows happened." }, "reason": { "type": [ "string", "null" ], "description": "Why it is in the feed, for display." }, "actor": { "type": "object", "properties": { "id": { "type": "string", "description": "User id." }, "username": { "type": "string", "description": "Username." }, "displayName": { "type": [ "string", "null" ], "description": "Display name." }, "avatarUrl": { "type": [ "string", "null" ], "description": "Profile picture." } }, "required": [], "additionalProperties": false, "description": "Who did it, on cards about someone’s activity." }, "music": { "$ref": "#/components/schemas/MusicSummary" }, "value": { "type": [ "integer", "null" ], "description": "On `rating` and `review` cards: the rating, 0–100. `null` for a review given without one." }, "review": { "type": "object", "description": "On `review` cards: the review.", "additionalProperties": true }, "session": { "type": [ "object", "null" ], "description": "On `rating` cards: other ratings made at the same sitting.", "additionalProperties": true }, "users": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "On `suggested_users` cards: the people suggested." }, "insight": { "type": "object", "description": "On `insight` cards: the insight.", "additionalProperties": true }, "list": { "type": "object", "description": "On `list` cards: the list.", "additionalProperties": true }, "stats": { "type": "object", "description": "On `trending` and `new_release` cards: its numbers.", "additionalProperties": true }, "period": { "type": "string", "description": "On `trending` and `new_release` cards: the period it covers." }, "activityId": { "type": [ "string", "null" ], "description": "The activity the card shows, when it shows one." }, "engagement": { "type": "object", "description": "Counts of reactions and comments.", "additionalProperties": { "type": "integer" } } } } } } }