API Enhancement Requests

[wescopeland]

edit: please see #2081 (comment)

---

Is the API missing data or would you like something changed/improved to better suit your needs? Place your request here so we don't lose it.

You can also find API support in our #coders channel on Discord: https://discord.com/channels/310192285306454017/645777658319208448

[ioslife]

Getting Achievement Type on would be helpful – API_GetUserRecentAchievements

I pulled down RAWeb and was gonna make a change for this, assuming it would be as simple as it was to add it to getAchievementUnlocks. Alas, it looks like this change would require a change to the DB query. It looks like it should just be adding ach.Type to getAchievementsEarnedBetween in player-history.php, but not sure if changing that has any other repercussion. So I will simply keep this as a request rather than a PR 😅

[wescopeland]

Resolved by #2089.

[Hexadigital]

One endpoint that I would love to see, for use in things like stream overlays and progress widgets, is an endpoint that takes in a game ID and username, and returns information relating to the game and user progress.
For the game: game title, game badge image URL, game console/platform name, total points earned, total points in set
For the achievements earned: achievement title, achievement point value, achievement image URL, achievement type (if possible), and achievement unlock timestamp (preferably unix time, or including timezone, if possible)

If possible, I'd like the game ID to be optional - and if omitted, it could use the latest game ID from the user's profile (either the latest rich presence game, or the first game in the activity list on the profile)

I'm currently using that information in a stream overlay like the below image, but I think it would be less intensive on the server to have a dedicated query, since otherwise I need to use multiple endpoints to fetch and discard a lot of information that isn't needed.

[LaunchBox-C-Beats]

Pretty sure you just described the getGameInfoAndUserProgress endpoint found here: https://api-docs.retroachievements.org/v1/users/get-game-info-and-user-progress.html

[Hexadigital]

Yeah, it does look like that endpoint has everything but the achievement type - at the moment I'm using that endpoint in conjunction with GetUserRecentlyPlayedGames (to figure out the latest game played) and that seems to work well.

[wescopeland]

A large portion of this is likely handled by #2122.

[Hexadigital]

I'd like to bump this as a separate request again - GetGameInfoAndUserProgress and GetUserRecentlyPlayedGames are both down/disabled at the moment, so a more reliable endpoint would be appreciated.

[ioslife]

Another endpoint that I mentioned (Wes said he would look into it already, just adding here to not lose track) is something that returns filterAndJoinGames results from https://github.com/RetroAchievements/RAWeb/blob/master/app/Platform/Services/PlayerProgressionService.php

This would allow consumers to have access to the already combined user recent progress and user site awards calls.

[wescopeland]

I believe this might pair nicely with what @Hexadigital is proposing for a new API_GetUserGameProgression (?) endpoint in #2081 (comment).

[wescopeland]

#2122

[rsubtil]

(forwarded suggestion from Discord)

One addition that I believe is really useful is an endpoint to fetch the game ID (if existing) by supplying the computed game hash (according to https://docs.retroachievements.org/Game-Identification/) instead. This would be really useful for software that's more "general" purpose, such as emulator frontends.

[wescopeland]

Will be resolved by #2090.

[rsubtil]

Since #2090 was closed in favor of using the getGameList endpoint, considering the amount of information returned, I'd like to keep my usage of this endpoint to a minimum to avoid a lot of traffic/processing on your end.

Can I reasonably assume that a game's hashes are immutable, and stay the same for a long period of time, such as a few months/years? If yes, I can keep such information cached on the client, and only make requests when there's no existing local information about a game's hash.

[wescopeland]

Yes, it is a reasonable assumption that a game's hashes tend not to change very often, often in the timespan of months or years.

However, one thing I am curious about -- how is your front-end actually hashing the games?

[rsubtil]

However, one thing I am curious about -- how is your front-end actually hashing the games?

I use the official hash module from rcheevos, which I had to port to Godot, available here: https://github.com/retrohub-org/godot-rcheevos-rhash

[wescopeland]

Awesome! Do you happen to be in the RetroAchievements Discord? If so, can you please DM me?

[LaunchBox-C-Beats]

Right now in LaunchBox there is a window that displays the Top Ten user leaderboard. We get the information from GetTopTenUsers. Right now after making that call we then have to call GetUserSummary 10x so that we can get those users profile pic to display in said leaderboard. Would save the number of API calls we'd have to make if that information was returned in the GetTopTenUsers return set.

[wescopeland]

It probably makes sense to include the user's highest award level on the game info & user progress call. Now with beaten awards introduced, this is unclear without making an additional call to get user awards.

[wescopeland]

#2122

[ioslife]

Add pagination to API_GetUserCompletedGames

Calling for a user that has a ton of records (i.e. MaxMilyin) is significantly slower (1106 ms) than a user with fewer records (i.e. Bronson15 – 263 ms)

[wescopeland]

Not sure how to do this in a way that's not a breaking change.

[ioslife]

I also didn't have an idea. Just wanted to add that it would be helpful :)

[LaunchBox-C-Beats]

This is coming from a C# dev who admittedly has little web experience, but the concept sounds doable to me. Would it be possible to add two optional parameters for page number and records per page. Page number defaults to null, records per page can default to whatever makes most sense. Then in the API logic is page number is null return the full dataset, otherwise return the number of records requested. Consumer would know to call for more pages if the number of results returned was the same as the results per page count, stop when the number of records is less than that.

[wescopeland]

#2122 will support pagination and return only 1 record per each game.

[ioslife]

Merry Christmas! Thanks for all these updates!!

[ioslife]

Add Achievement Image URL to API_GetAchievementOfTheWeek

[wescopeland]

#2121

[ioslife]

Return softcore points in API_GetAchievementUnlocks

[wescopeland]

Not sure I completely follow this request. Can you clarify? I see Points being returned, which is going to always be the same for both hardcore and softcore.

[ioslife]

Yeah, sorry. AchievementUnlocks returns

{
"user": "Podgicus0305",
"raPoints": 15544,
"dateAwarded": "2022-07-12 19:06:34",
"hardcoreMode": true
}

I believe raPoints is hardcore, but I’d like to get softcore too for those that don’t play hardcore.

[ioslife]

#2495

[ioslife]

Add endpoints for:
• GET and POST(!) Want to Play games
• GET and POST(!) Follow/Unfollow users

[wescopeland]

What response shapes would be desirable for these GET requests?

[ioslife]

Followed user would be nice to have something like this:

FollowedUser {
	username: "Bronson15",
	points: 999999,
	softcorePoints: 999999
}

GetFollowedUsers {
	[
		FollowedUser1,
		FollowedUser2,
		FollowedUser3
	]
}

WantToPlayGames would be nice to have something like this:

WantToPlayGame {
	id: 1,
	name: "Sonic the Hedgehog"",
	consoleName: "Genesis",
	imageIcon: "/url/here.png",
	maxPossible: 70,
	numAwarded: 35,
	numAwardedHardcore: 15
}

GetWantToPlayGames {
	[
		WantToPlayGame1,
		WantToPlayGame2,
		WantToPlayGame3
	]
}

[joamjoamjoam]

Plus one for this. It would nice to manage the want to play list through the API.

[ioslife]

Plus one for this. It would nice to manage the want to play list through the API.

I started working on this. For now it will only be a GET request, so managing via API will not be possible.

#2549

[Hexadigital]

I don't know how much interest there would be in it outside of my use case, but one thing that I was doing before (that I can't do now) was sending a POST request to reorderSiteAwards.php, in order to systematically sort my badges. If there was an API endpoint that took in an ordered list of game ID's (at a minimum) or a more complicated structure and updated the user's profile accordingly, that would be greatly appreciated.

[Nepiki]

Posted this on Discord as well, but it would be ideal if the getUserCompletedGames endpoint could account for progression (unfinished, beaten, mastered) so we can determine a game's state on import/daily sync.

[wescopeland]

#2122

[ioslife]

Add an endpoint to return the New Sets/Revisions list

[ioslife]

This actually is accessible via the getClaims call and sorting on UpdatedDate. getClaims seems to return all claims (when do they fall off of this call?), so it would be cool to have a way to only get the most recent X amount of days

[evanation]

Hi!
Please, add 'Release' for API_GetGameList.php
and add rom name in hash table for API_GetGameList.php too

[ccreight]

Hi! I was wondering what the best way to get the image for a certain achievement was? I'm currently calling the API to get the achievement of the week, and that works alright, but I'm only able to access the achievement's ID:

achievementOfTheWeek.achievement.id

Not the actual badge's ID, to put that into a URL like this: https://i.retroachievements.org/Badge/341926.png

is there a different way I should be getting the badge image? thank you so much!

[ccreight]

ah nevermind, I found a workaround by calling for the extended game data of the related game and then finding the specific achievement's info!

[ioslife]

If you’re specifically concerned about AotW, #2121 is adding the imageURL to the response

[likeich]

I'm working on the next big update to Console Launcher that has ROM frontend support. Right now I'm adding the ability to view RetroAchievements. It's been fun to add them since it makes it much more like a game console!

I have already added the achievement views for each game and console. The next feature I'm adding is viewing your followed/following list of friends, if they are active, etc. With this, it would be amazing to eventually message through the RA API as well. I would love to add a basic chat client to Console Launcher to message RA users from within the app.

Platform with All Games	Super Mario World Cheevos

[EtherialNL]

I'm monitoring the New and Updated sets by calling the appropriate GetClaims endpoint.

According to the API documentation, about 1,000 records should be returned, but I received 11,270 records instead—with GameID 3 as the oldest—so it seems all records are being returned.

Would it be possible to add a parameter to define how many records should be returned?

The full response size (when using ClaimKind = 1) is around 4.3 MB, so limiting the number of records could help reduce bandwidth usage.

[biscuitcakes]

I'd love a way to query if an emulator is supported or not without having to launch a game. I may try to tackle it but wanted to post here anyway :)

[adamantike]

It would be great to have information regarding Hubs, like:

• Get Hub information by Hub ID, including Game IDs associated to that hub.
• List Hubs a game is part of (in the Game Extended Details endpoint, or a different one).

[turner485]

It would be great to get to have an endpoint related to the "Just Released" sets.
IE: https://retroachievements.org/claims/completed

[wescopeland]

This should be doable by using the k param on this endpoint: https://api-docs.retroachievements.org/v1/get-claims.html

[turner485]

Amazing thank you @wescopeland .

Is there any end point that points to this page?
https://retroachievements.org/game/33579/hashes?

[Bregann]

It'd be handy for the API_GetUserCompletionProgress endpoint if we could get the total points earned by the user for each game for softcore/hardcode

[m1guelpf]

I'd love to be able to access rich_presence_updated_at (from PlayerSession) in API_GetUserSummary or API_GetUserData

[m1guelpf]

Opened #4156 to address this

[MaXXimumBuB]

Is there something for PostComment and DeleteComment? I would like to be able to utilize this.

Thank you.

[wescopeland]

Sorry, our API is currently read-only.

[MaXXimumBuB]

I thought so, and it makes sense, but just wanted to ask to be sure I didn’t miss it. Thank you. On Nov 21, 2025, at 2:46 PM, Wes Copeland ***@***.***> wrote:  Sorry, our API is currently read-only. — Reply to this email directly, view it on GitHub<#2081 (reply in thread)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/A2TX5S5YGJZ5P7A6OUDAD3D355TXZAVCNFSM6AAAAABALYKVAOVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTKMBUGE2TQNI>. You are receiving this because you commented.Message ID: ***@***.***>

[Bryan1150]

I was trying to grab data from the API to make custom series/hub leaderboards for fun but I ran into 2 issues:

1. There doesn't seem to be available calls to get the data from which games are contained in a hub, this can be worked around by manually grabbing the games from the hub, but it would be nice to have a call with the hub id that returns every game in that hub
2. getGameRankAndScore only returns the top 10, so I wonder how doable it would be to have a parameter to grab it fully or atleast more than just top 10.

Sorry if those requests sound too specific for my use case, I could try my hand at implementing them if they seem to overall make sense.

[RagunovichVlad]

If possible, it would be great to add a totalPlaytime field to the following endpoints:

• API_GetUserRecentlyPlayedGames.php
• API_GetUserCompletionProgress.php

If that’s not feasible everywhere right now, it would be great adding it at least to:

• API_GetGameInfoAndUserProgress.php

[m1guelpf]

Opened #4270 for this

[wescopeland]

Important Notice

Once #4270 and #4210 are merged, we are placing an indefinite code freeze on our V1 (current) API. It will continue functioning without interruption, but all API enhancements will shift towards our new V2 web API that is under active development.

The V2 API features significantly enhanced functionality, including OAuth2 support and advanced filtering/sorting of resources. You can follow along here: https://github.com/RetroAchievements/RAWeb/pulls?q=feat%28api%29+V2

[DFelten]

Is it somehow possible to fetch the progress of an achievement?

For example fetch the amount of trainers I've already beaten on a route of Pokémon Black for a specific achievement. The emulator is able to show me the amount.

Or is this something which is only a part of the Savegame and not of the RA database?

[wescopeland]

Unfortunately we don't track this in the DB. It's something detected in-emulator by the achievement logic itself.

[UGamer]

Wasn't sure whether to request this now or wait until V2 is rolling, I understand y'all are hard at work on that as is!

The Achievement of the Week endpoint is awesome, and I was wondering what the likelihood of a similar endpoint for Achievement of the Month would be?

Additionally, how about one for RA Roulette? At that point maybe even a general endpoint for events where you provide the ID and it returns a list of the achievements in it.

Thank you for all that you do!

[branpg]

I want to fetch the number of set request a game has but I could only find an endpoint to get requests by user.
I would love to have it added to the Game Extended Details if not available (So I don't have to consume more bandwith to get this).
I use my integration to the api to track my played games and I would love to use it to search for games to develop a set for. I'm currently quering my db to ask for completed games that dont have a set yet or an active claim, but I would love to be able to sort them to see wich ones have more requests.