Getting Started

The RetroAchievements API allows developers to access a wealth of data from the RetroAchievements platform, including information about games, users, and achievements. This page covers the primary ways to interact with the API: making direct HTTP requests or using a client library.

• Get Your Web API Key
• Quick Start (HTTP Requests)
• Quick Start (Client Library)

Get Your Web API Key

You will need a web API key. To get one, follow these steps:

1. While authenticated, visit your control panel on the RetroAchievements website.
2. Find the "Keys" section on the page. Copy the web API key value.

WARNING

Store your API key as though it is a secret, like a password. Avoid checking in your API key with your code.

Quick Start (HTTP Requests)

With your web API key, you now have all you need to call any endpoint in the API.

curl https://retroachievements.org/API/API_GetTopTenUsers.php?&y=[your_key]

Quick Start (Client Library)

Platform / Language	Repo
NodeJS (JavaScript)	RetroAchievements/api-js
JVM (Kotlin)	RetroAchievements/api-kotlin

Currently, our official client libraries are for JavaScript/TypeScript/NodeJS and Kotlin. Additional client libraries will be added in the future for other tech stacks and platforms.

To use one of our client libraries, you'll need to first install the package corresponding to your tech stack. Then, you'll create an authentication object. After these steps are completed, you are able to use any function provided by the library.

NodeJS

npm install --save @retroachievements/api

Kotlin + Maven

<!-- add the jitpack.io repository to your `pom.xml` </repositories> -->
<repository>
    <id>jitpack.io</id>
    <url>https://www.jitpack.io</url>
</repository>

<!-- Then you'll be able to import the kotlin library by adding the following dependency to your `pom.xml` </dependencies> -->
<dependency>
    <groupId>com.github.RetroAchievements</groupId>
    <artifactId>api-kotlin</artifactId>
    <version>1.0.1</version>
</dependency>

Kotlin + Gradle

// Add it in your root build.gradle at the end of repositories:
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}

// Add the dependency
dependencies {
    implementation 'com.github.RetroAchievements:api-kotlin:1.0.1'
}

You can now create your authorization object using your RA username & web API key.

NodeJS

import { buildAuthorization } from "@retroachievements/api";

const username = "<your username on RA>";
const webApiKey = "<your web API key>";

const authorization = buildAuthorization({ username, webApiKey });

Kotlin

val credentials = RetroCredentials("<username>", "<web api key>")
val api: RetroInterface = RetroClient(credentials).api

// access the api interface in `api`

You now have all you need to use any function in the API. Here's a basic example of how to access the API:

NodeJS

import { getGame } from "@retroachievements/api";

// Each function takes this authorization object as its first argument. Here's an example:
// This returns basic metadata about the game on this page:
// https://retroachievements.org/game/14402
const game = await getGame(authorization, { gameId: 14402 });

Kotlin

// This returns basic metadata about the game on this page:
// https://retroachievements.org/game/14402
val response: NetworkResponse<GetGame.Response, ErrorResponse> = api.getGame(
    gameId = 14402
)