{"openapi":"3.1.0","info":{"title":"Partita API","version":"1.0.0","description":"Artist resolution API: any artist URL in, canonical identity plus the full cross-platform link graph out. Free and keyless for reads; rate limited per IP (60 requests/minute). art_ IDs are permanent. Docs: https://partita.io/docs"},"servers":[{"url":"https://api.partita.io/v1"}],"components":{"schemas":{"ArtistImage":{"type":"object","properties":{"url":{"type":"string"},"width":{"type":"number"},"height":{"type":"number"}},"required":["url","width","height"]},"ArtistLink":{"type":"object","properties":{"platform":{"type":"string","description":"Detected platform of the link (instagram, tiktok, youtube, bandcamp, …). 40+ types.","example":"instagram"},"url":{"type":"string","example":"https://instagram.com/taylorswift"},"verified":{"type":"boolean","description":"True if editorially verified, false if scraped."}},"required":["platform","url","verified"]},"SpotifyStats":{"type":["object","null"],"properties":{"followers":{"type":"number","example":129000000},"popularity":{"type":"number","description":"Spotify popularity, 0–100.","example":100},"monthlyListeners":{"type":["number","null"]},"worldRank":{"type":["number","null"]},"updatedAt":{"type":"string","description":"ISO 8601 timestamp of the last stats refresh.","example":"2026-08-15T02:00:00.000Z"}},"required":["followers","popularity","monthlyListeners","worldRank","updatedAt"],"description":"Spotify stats, or null when none are on record."},"Artist":{"type":"object","properties":{"id":{"type":"string","description":"Permanent Partita artist ID. Never changes or gets recycled.","example":"art_2Fw8XoYb3kQpVZC"},"name":{"type":"string","example":"Taylor Swift"},"genres":{"type":"array","items":{"type":"string"},"example":["pop"]},"imageUrl":{"type":["string","null"],"description":"Largest available artist image."},"images":{"type":"array","items":{"$ref":"#/components/schemas/ArtistImage"}},"links":{"type":"array","items":{"$ref":"#/components/schemas/ArtistLink"},"description":"Cross-platform link graph (a sameAs set for the artist)."},"spotify":{"$ref":"#/components/schemas/SpotifyStats"},"updatedAt":{"type":["string","null"],"description":"ISO 8601 timestamp of the last update to the artist record.","example":"2026-08-18T11:20:00.000Z"}},"required":["id","name","genres","imageUrl","images","links","spotify","updatedAt"]},"NotFoundError":{"type":"object","properties":{"error":{"type":"string","enum":["not_found"]}},"required":["error"]},"RateLimitedError":{"type":"object","properties":{"error":{"type":"string","enum":["rate_limited"]}},"required":["error"]},"ResolveResponse":{"type":"object","properties":{"match":{"type":"object","properties":{"platform":{"type":"string","example":"spotify"},"externalId":{"type":"string","description":"The platform-native ID or handle parsed from the URL.","example":"06HL4z0CvFAxyc27GXpf02"},"url":{"type":"string"},"verified":{"type":"boolean","description":"True if the matched identity is editorially verified, false if scraped."}},"required":["platform","externalId","url","verified"]},"artist":{"$ref":"#/components/schemas/Artist"}},"required":["match","artist"]},"ArtistSuggestion":{"type":"object","properties":{"id":{"type":"string","example":"art_2Fw8XoYb3kQpVZC"},"name":{"type":"string","example":"Taylor Swift"},"imageUrl":{"type":["string","null"]}},"required":["id","name","imageUrl"]},"InvalidRequestError":{"type":"object","properties":{"error":{"type":"string","enum":["invalid_request"]},"issues":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}},"required":["path","message"]}}},"required":["error","issues"]},"ResolveBadRequest":{"anyOf":[{"type":"object","properties":{"error":{"type":"string","enum":["invalid_url"]}},"required":["error"]},{"type":"object","properties":{"error":{"type":"string","enum":["unsupported_platform"]},"suggestions":{"type":"array","items":{"$ref":"#/components/schemas/ArtistSuggestion"}}},"required":["error","suggestions"]},{"$ref":"#/components/schemas/InvalidRequestError"}]},"ResolveNotFound":{"type":"object","properties":{"error":{"type":"string","enum":["not_found"]},"suggestions":{"type":"array","items":{"$ref":"#/components/schemas/ArtistSuggestion"}}},"required":["error","suggestions"]}},"parameters":{}},"paths":{"/artists/{id}":{"get":{"operationId":"getArtist","summary":"Get an artist by ID","description":"Look up an artist by its permanent art_ ID. A pure cached read; the link graph refreshes in the background when stale.","parameters":[{"schema":{"type":"string","description":"Permanent art_ artist ID. Legacy Spotify IDs are accepted for back-compat.","example":"art_2Fw8XoYb3kQpVZC"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The artist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Artist"}}}},"404":{"description":"No artist with this ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundError"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}}}},"/resolve":{"get":{"operationId":"resolveArtistUrl","summary":"Resolve an artist URL to a canonical artist","description":"Any supported artist URL in, canonical identity plus the full cross-platform link graph out — in one call.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Artist URL on a supported platform: spotify, apple_music, instagram, soundcloud, tiktok, twitter, youtube, amazon_music, wikipedia.","example":"https://open.spotify.com/artist/06HL4z0CvFAxyc27GXpf02"},"required":true,"name":"url","in":"query"}],"responses":{"200":{"description":"Resolved artist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveResponse"}}}},"400":{"description":"URL unparseable (invalid_url) or on a platform that can't be resolved directly (unsupported_platform, with name-based suggestions)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveBadRequest"}}}},"404":{"description":"No artist matches the URL; name-based suggestions when the handle is usable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveNotFound"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitedError"}}}}}}}},"webhooks":{}}