NAV
cURL

Introduction

Welcome to the LootLocker Game API Reference Documentation.

We do our best to keep this documentation up to date, but if you find any issues, please reach out to us at hello@lootlocker.com, or swing by our Discord Server and talk to us directly.

Authentication

Starting a Player Session

Before you can call any of the other endpoints, you first need to start a player session.

You can register sessions with any of the below listed options, and you will receive a session_token in the response. This token is used to identify the player in subsequent requests.

Guest Login

Steam

PlayStation Network

Amazon Luna

Android

Sign in With Apple

Sign in With Apple Game Center

Sign in with Google

Sign in with Epic

Sign in with Meta

Nintendo Switch

Xbox

White Label Login

Remote Sign In

Using The Game Session Token

Sending along a session token in a POST request

curl -X POST "https://api.lootlocker.io/game/v1/some_endpoint_here" \
  -d "other_parameter=other_value" \
  -H "x-session-token: your_token_here"

All session registration calls will return a session_token, which is used to identify the player in subsequent requests.

The session token is sent as a HTTP header, with the name x-session-token. If this is not sent with a request, an authentication error will be returned.

Authentication Request

Registering a session:

# Session registration example with Steam
curl -X POST "https://api.lootlocker.io/game/v2/session" \
  -H "Content-Type: application/json" \
  -d "{\"game_key\": \"your_game_key\", \"platform\": \"steam\", \"player_identifier\": \"76561198023004363\", \"game_version\": \"0.10.0.0\"}"

The game API uses the API key for the initial request which registers a session.

Four parameters are expected in this request, with three additional optional parameters.

A successful response looks like this:

{
  "success": true,
  "session_token": "e6fa44946f077dd9fe67311ab3f188c596df9969",
  "player_id": 3,
  "player_name": "John Doe", // null if the player has not set a name yet
  "public_uid": "TSEYDXD8",
  "player_created_at": "2022-05-30T07:56:01+00:00",
  "check_grant_notifications": true,
  "check_deactivation_notifications": false,
  "seen_before": true
}

Required: player_identifier, game_key, game_version and platform.

Optional: mac and session_id

Deprecated: development_mode (optional)

player_identifier being the ID of the player on the platform the game is currently running on (steamId, PSN id, etc)

game_key being your API key

game_version being the current version of the game in the format 1.2.3.4 (the 3 and 4 being optional but recommended)

mac (OPTIONAL) being the MAC address of the computer the user is currently playing on. This is used for submitting crash logs later and being able to connect it with a player.

session_id (OPTIONAL) being a randomly generated string to identify this current session.

development_mode (DEPRECATED) is a boolean flag you can set to true if you want to start a session for the development environment.

This property has been deprecated, since API keys specifies which environment to use. If you're using legacy game_keys, this can still be supplied.

platform being the name of the platform the user is on, we currently support the following:

Platform Parameter value Reference name Note
Steam steam 64-bit SteamID
Playstation Network psn Online ID
iOS ios Device ID Deprecated, see Sign in With Apple instead.
Android android Device ID
Amazon Luna luna Amazon Luna GUID

session_token is the token you need to make game api calls on behalf of the player. To see how to send that along with further requests, see Using the game session token.

player_id is the player's id in LootLocker. This can be used to integrate with third party tools such as Game Analytics and later generate reports on a per player basis.

public_uid is a unique id for a player in your game, that can be used for searching for the player in the LootLocker Player Manager, or used by players to interact with other players, such as sending friend requests, or requesting UGC created by a specific player.

The check_grant_notifications parameter is for cases where the registration of a session might have triggered asynchronously granting assets the the player. Eg. during DLC migration. If this value is true, you should issue a request for the player asset notification endpoint no earlier than 5 minutes after registering the session.

The check_deactivation_notifications is for letting users know that one of their assets have been deactivated since they last logged in, and can't be used. See Player Asset Deactivation Notifications.

If your game uses constant DLC migrations, you will get ID's back of the DLC's you should check with Steam to see if the player owns them. If you own any of them, issue a call to the Initiate DLC Migration endpoint.

A successful response for a game using XP:

{
  "success": true,
  "session_token": "e6fa44946f077dd9fe67311ab3f188c596df9969",
  "player_id": 3,
  "public_uid": "TSEYDXD8",
  "player_created_at": "2022-05-30T07:56:01+00:00",
  "check_grant_notifications": true,
  "check_deactivation_notifications": false,
  "xp": 5,
  "level": 0,
  "seen_before": true
}

A successful response for a game using soft currency:

{
  "success": true,
  "session_token": "e6fa44946f077dd9fe67311ab3f188c596df9969",
  "player_id": 3,
  "public_uid": "TSEYDXD8",
  "player_created_at": "2022-05-30T07:56:01+00:00",
  "check_grant_notifications": true,
  "check_deactivation_notifications": false,
  "account_balance": 1856,
  "seen_before": true
}

A successful response for a game using constant DLC migrations:

{
  "success": true,
  "session_token": "9178407f966bc58f79acbf96b030eaf43738ab84",
  "player_id": 12,
  "public_uid": "TSEYDXD8",
  "player_created_at": "2022-05-30T07:56:01+00:00",
  "seen_before": true,
  "check_grant_notifications": true,
  "check_deactivation_notifications": true,
  "check_dlcs": [438800, 438801, 438802, 439210],
  "xp": 183188,
  "level": 44,
  "level_thresholds": {
    "current": 352300,
    "current_is_prestige": false,
    "next": 362300,
    "next_is_prestige": true
  },
  "account_balance": 97
}

Guest Login

Register New Guest Session Request

curl -X POST "https://api.lootlocker.io/game/v2/session/guest" \
  -H "Content-Type: application/json" \
  -d "{\"game_key\": \"your_game_key\", \"game_version\": \"0.10.0.0\"}"

Guest Login is very similar to the other Authentication methods, except that it does away with the platform property in the request body, makes the player_identifier property optional and will return the player_identifier in the response.

The Guest Login should be used when you do not wish to burden your user with having to create an account on one of the other platforms that LootLocker supports. However, it is important to understand that there is no security for these Guest accounts, and if someone can guess the player_identifier of an existing player, they will be able to play as that player.

Register Existing Guest Session Request

curl -X POST "https://api.lootlocker.io/game/v2/session/guest" \
  -H "Content-Type: application/json" \
  -d "{\"game_key\": \"your_game_key\", \"player_identifier\": \"ec9b35e6-b184-4f34-b49f-980f86b291e2\", \"game_version\": \"0.10.0.0\"}"

When using the Guest login, you should nudge your users to migrate to a persistent platform.

The response from this endpoint is almost identical to the one from the normal Authentication call, with the exception that a player_identifier is also returned, that can be used for subsequent authentication calls, to keep the same guest account active over multiple sessions.

Example Response

{
  "success": true,
  "session_token": "e6fa44946f077dd9fe67311ab3f188c596df9969",
  "player_id": 3,
  "public_uid": "TSEYDXD8",
  "player_identifier": "ec9b35e6-b184-4f34-b49f-980f86b291e2",
  "player_created_at": "2022-05-30T07:56:01+00:00",
  "check_grant_notifications": true,
  "check_deactivation_notifications": false,
  "seen_before": true
}

White Label Authentication

White label login is an email + password authentication platform delivered by Lootlocker, where the registered users are tied to your Lootlocker organization.

Instead of sending a platform and player identifier we send an email and a white-label token, which has previously been retrieved via the white label login endpoint.

Registering a session:

curl -X POST "https://api.lootlocker.io/game/v2/session/white-label" \
  -H "Content-Type: application/json" \
  -d "{\"game_key\": \"your_game_key\", \"email\": \"test@lootlocker.io\", \"token\": \"afccd38d-09d5-48aa-8235-b9c4c9151596\", \"game_version\": \"0.10.0.0\"}"

A successful response looks like this:

{
  "success": true,
  "session_token": "e6fa44946f077dd9fe67311ab3f188c596df9969",
  "player_id": 3,
  "public_uid": "TSEYDXD8",
  "player_created_at": "2022-05-30T07:56:01+00:00",
  "check_grant_notifications": true,
  "check_deactivation_notifications": false,
  "seen_before": true
}

Nintendo Switch

Example Nintendo Switch session registration request

curl -X POST "https://api.lootlocker.io/game/session/nintendo-switch" \
  -H "LL-Version: 2021-03-01" \
  -H "Content-Type: application/json" \
  -d "{\"game_key\": \"your_game_key\", \"nsa_id_token\": \"eyJQa....\", \"game_version\": \"1.0.0.0\", \"session_id\": \"8438f4b3-90e4-4cdd-8434-c5c6b4c2c9f1\"}"

To register a session for a player on a Nintendo Switch, you need to obtain an NSA ID Token from a Nintendo Switch console. The token is in JWT format, and needs to be provided as a string in the nsa_id_token property of the request body. All other properties in this request follow the normal LootLocker authentication flow.

As the NSA ID Token already contains the player identifier, this endpoint does not need that identifier.

Example Response

{
  "success": true,
  "session_token": "e6fa44946f077dd9fe67311ab3f188c596df9969",
  "player_id": 3,
  "public_uid": "TSEYDXD8",
  "player_created_at": "2022-05-30T07:56:01+00:00",
  "check_grant_notifications": true,
  "check_deactivation_notifications": false,
  "seen_before": true
}

The response from this endpoint is also like all other platforms, and can be seen in the example.

Sign in with Apple

Example Sign in with Apple session registration request

curl -X POST "https://api.lootlocker.io/game/session/apple" \
  -H "LL-Version: 2021-03-01" \
  -H "Content-Type: application/json" \
  -d "{\"game_key\": \"your_game_key\", \"apple_authorization_code\": \"eyJQa....\", \"game_version\": \"1.0.0.0\", \"session_id\": \"8438f4b3-90e4-4cdd-8434-c5c6b4c2c9f1\"}"

To register a session for a player using Sign in with Apple, you need to obtain an authorization code from Apple. The token needs to be provided as a string in the apple_authorization_code property of the request body. All other properties in this request follow the normal LootLocker authentication flow.

A refresh token will be returned in the session response. This token can be stored on the client and sent in place of the apple_authorization_code, in the field refresh_token. This way you can start subsequent LootLocker sessions without having to initiate the full Sign In With Apple flow on the device.

Example Refresh Apple session request

curl -X POST "https://api.lootlocker.io/game/session/apple" \
  -H "LL-Version: 2021-03-01" \
  -H "Content-Type: application/json" \
  -d "{\"game_key\": \"your_game_key\", \"refresh_token\": \"748b....\", \"player_identifier\": \"765..\", \"game_version\": \"1.0.0.0\", \"session_id\": \"8438f4b3-90e4-4cdd-8434-c5c6b4c2c9f1\"}"

The underlying Apple session will be verified on LootLocker servers when sending refresh_token. If Apple has invalidated the session, this endpoint will return a 400 status code. If you receive this status code, you should do the full authentication flow with Sign In With Apple, and send the apple_authorization_code to start a new session.

More information can be found in the LootLocker docs.

Example Response

{
  "success": true,
  "session_token": "e6fa44946f077dd9fe67311ab3f188c596df9969",
  "player_id": 3,
  "public_uid": "TSEYDXD8",
  "player_created_at": "2022-05-30T07:56:01+00:00",
  "check_grant_notifications": true,
  "check_deactivation_notifications": false,
  "seen_before": true,
  "refresh_token": "748b5ac8-794a-44e3-bb59-c59a2f397e84",
  "player_identifier": "76561198023004363"
}

The response from this endpoint is also like all other platforms, and can be seen in the example.

Sign in with Apple Game Center

To register a session for a player using Apple Game Center, you need to obtain the necessary parameters.

Example Sign in with Apple Game Center session registration request

curl -X POST "https://api.lootlocker.io/game/session/apple/game-center" \
  -H "LL-Version: 2021-03-01" \
  -H "Content-Type: application/json" \
  -d "{\"game_key\": \"your_game_key\", \"bundle_id\": \"apple.bundle.id\", \"player_id\": \"T:_e66eaa73fcd186b1b3e9dc22e19398e4\", \"public_key_url\": \"https://static.gc.apple.com/public-key/gc-prod-9.cer\", \"signature\": \"x+D8j5ulh6/m1O6yW5mKuaX ... G3vEwHLxsYGLjSVn53XVshIFL528=\", \"salt\": \"UIzs/Q==\", \"timestamp\": 1680781286451, \"game_version\": \"1.0.0.0\" }"
{
  "game_key": "your_game_key",
  "game_version": "1.0.0.0",
  "bundle_id": "apple.bundle.id",
  "player_id": "T:_e66eaa73fcd186b1b3e9dc22e19398e4",
  "public_key_url": "https://static.gc.apple.com/public-key/gc-prod-9.cer",
  "signature": "x+D8j5ulh6/m1O6yW5mKuaXz ... G3vEwHLxsYGLjSVn53XVshIFL528=",
  "salt": "UIzs/Q==",
  "timestamp": 1680781286451
}

Example Start Apple Game Center session response

{
  "session_token": "eb13a7bf17efg36cb8481a8ds18809c7e85686e6",
  "player_id": 9358,
  "public_uid": "J72YP6MS",
  "player_name": null,
  "player_created_at": "2023-02-21T15:33:25+00:00",
  "check_grant_notifications": false,
  "check_deactivation_notifications": false,
  "seen_before": false,
  "refresh_token": "eyJh............................."
}

With the session response, you will get a refresh_token which you can save on your device. This token can be used to start new sessions without having to go through the full authentication process each time. Simply pass it in the refresh_token field, instead of the other parameters.

However, if your refresh_token has expired and you try to use it, you will get an error message with a 400 status code. In this case, you will need to go through the full Apple Game Center authentication process to get a new refresh_token.

Example Refresh Apple Game Center session request

curl -X POST "https://api.lootlocker.io/game/session/apple/game-center" \
  -H "LL-Version: 2021-03-01" \
  -H "Content-Type: application/json" \
  -d "{\"game_key\": \"your_game_key\", \"refresh_token\": \"748b....\", \"game_version\": \"1.0.0.0\" }"
{
  "game_key": "your_game_key",
  "game_version": "1.0.0.0",
  "refresh_token": "eyJh............................."
}

Example Refresh Apple Game Center session response

{
  "session_token": "eb13a7bf17efg36cb8481a8ds18809c7e85686e6",
  "player_id": 9358,
  "public_uid": "J72YP6MS",
  "player_name": null,
  "player_created_at": "2023-02-21T15:33:25+00:00",
  "check_grant_notifications": false,
  "check_deactivation_notifications": false,
  "seen_before": false,
  "refresh_token": "eyJh............................."
}

Sign in with Google

Example Sign in with Google session registration request

curl -X POST "https://api.lootlocker.io/game/session/google" \
  -H "LL-Version: 2021-03-01" \
  -H "Content-Type: application/json" \
  -d "{\"game_key\": \"your_game_key\", \"id_token\": \"eyJQa....\", \"game_version\": \"1.0.0.0\" }"

To register a session for a player using Sign in with Google, you need to obtain an ID token from Google. The token needs to be provided as a string in the id_token property of the request body. All other properties in this request follow the normal LootLocker authentication flow.

Optionally you can also specify your OAuth2 Client platform by sending the platform field in the session request, supported values are web, android, ios and desktop. If the platform is not specified the default OAuth2 Client Id will be used, You can set platform-specific OAuth2 Client Id's through the advanced options in the web console.

Example Sign in with Google session registration request with the platform specified

curl -X POST "https://api.lootlocker.io/game/session/google" \
  -H "LL-Version: 2021-03-01" \
  -H "Content-Type: application/json" \
  -d "{\"game_key\": \"your_game_key\", \"id_token\": \"eyJQa....\", \"game_version\": \"1.0.0.0\", \"platform\": \"web\" }"

A refresh token will be returned in the session response. This token can be stored on the client and sent in place of the id_token, in the field refresh_token. This way you can start subsequent LootLocker sessions without having to initiate the full Sign In With Google flow on the device.

Example Refresh Google session request

curl -X POST "https://api.lootlocker.io/game/session/google" \
  -H "LL-Version: 2021-03-01" \
  -H "Content-Type: application/json" \
  -d "{\"game_key\": \"your_game_key\", \"refresh_token\": \"748b....\", \"game_version\": \"1.0.0.0\" }"

If your refresh token expires, this endpoint will return a 400 status code. If you receive this status code, you should do the full authentication flow with Sign In With Google, and send the id_token to start a new session.

More information can be found in the LootLocker docs.

Example Response

{
  "session_token": "eb13a7bf17efg36cb8481a8ds18809c7e85686e6",
  "player_id": 9358,
  "public_uid": "J72YP6MS",
  "player_name": null,
  "player_created_at": "2023-02-21T15:33:25+00:00",
  "check_grant_notifications": false,
  "check_deactivation_notifications": false,
  "seen_before": true,
  "refresh_token": "eyJh............................."
}

Sign in with Epic Games

Example Sign in with Epic session registration request

curl -X POST "https://api.lootlocker.io/game/session/epic" \
  -H "LL-Version: 2021-03-01" \
  -H "Content-Type: application/json" \
  -d "{\"game_key\": \"your_game_key\", \"id_token\": \"eyJQa....\", \"game_version\": \"1.0.0.0\" }"

To register a session for a player using Sign in with Epic, you need to obtain an ID token from Epic. The token needs to be provided as a string in the id_token property of the request body. All other properties in this request follow the normal LootLocker authentication flow.

A refresh token will be returned in the session response. This token can be stored on the client and sent in place of the id_token, in the field refresh_token. This way you can start subsequent LootLocker sessions without having to initiate the full Sign In With Epic flow on the device.

Example Refresh Epic session request

curl -X POST "https://api.lootlocker.io/game/session/epic" \
  -H "LL-Version: 2021-03-01" \
  -H "Content-Type: application/json" \
  -d "{\"game_key\": \"your_game_key\", \"refresh_token\": \"748b....\", \"game_version\": \"1.0.0.0\" }"

If your refresh token expires, this endpoint will return a 400 status code. If you receive this status code, you should do the full authentication flow with Sign In With Epic, and send the id_token to start a new session.

More information can be found in the LootLocker docs.

Example Response

{
  "session_token": "eb13a7bf17efg36cb8481a8ds18809c7e85686e6",
  "player_id": 9358,
  "public_uid": "J72YP6MS",
  "player_name": null,
  "player_created_at": "2023-02-21T15:33:25+00:00",
  "check_grant_notifications": false,
  "check_deactivation_notifications": false,
  "seen_before": true,
  "refresh_token": "eyJh............................."
}

Sign in with Meta

Example Meta session registration request

curl -X POST "https://api.lootlocker.io/game/session/meta" \
  -H "LL-Version: 2021-03-01" \
  -H "Content-Type: application/json" \
  -d "{\"game_key\": \"your_game_key\", \"user_id\": \"1234567890\", \"nonce\": \"0987654321\", \"game_version\": \"1.0.0.0\" }"

To register a session for a player using Meta, you need to obtain user_id and nonce and then send those parameters in the request body. All other properties in this request follow the normal LootLocker authentication flow.

A refresh token will be returned in the session response. This token can be stored on the client and sent in place of user_id and nonce, in the field refresh_token. This way you can start subsequent LootLocker sessions without having to initiate the full Meta sign in flow on the device.

Example Refresh Meta session request

curl -X POST "https://api.lootlocker.io/game/session/meta" \
  -H "LL-Version: 2021-03-01" \
  -H "Content-Type: application/json" \
  -d "{\"game_key\": \"your_game_key\", \"refresh_token\": \"748b....\", \"game_version\": \"1.0.0.0\" }"

If your refresh token expires, this endpoint will return a 400 status code. If you receive this status code, you should do the full authentication flow with Sign In With Meta, and send the user_id and nonce parameters to start a new session.

More information can be found in the LootLocker docs.

Example Response

{
  "session_token": "eb13a7bf17efg36cb8481a8ds18809c7e85686e6",
  "player_id": 9358,
  "public_uid": "J72YP6MS",
  "player_name": null,
  "player_created_at": "2023-02-21T15:33:25+00:00",
  "check_grant_notifications": false,
  "check_deactivation_notifications": false,
  "seen_before": true,
  "refresh_token": "eyJh............................."
}

Remote Sign in Lease

Example Remote session lease request

curl -X POST "https://api.lootlocker.io/game/session/remote/lease" \
  -H "LL-Version: 2021-03-01" \
  -H "Content-Type: application/json" \
  -d "{\"game_key\": \"your_game_key\", \"game_version\": \"1.0.0.0\" }"

Remote session start with getting a lease code and nonce using the /game/session/remote/lease endpoint. After which you will have to call the Remote Sign in Session endpoint to start a session.

More information can be found in the LootLocker docs.

Example Remote session lease response

{
    "code": "R9SJMK2R",
    "nonce": "01HE2T5P3YY6XH4NY3BPVP4N07",
    "redirect_url": "https://auth.game/connect?code=R9SJMK2R",
    "redirect_url_qr_base64": "base64 image qr code representation of redirect_url",
    "display_url": "auth.game/connect",
    "status": "CREATED",
    "ip": "127.0.0.1"
}

Using the code and nonce, you can invoke the /game/session/remote endpoint to start a session.

The status of the lease is always present in the response and has multiple stages:

Status Note
CREATED The lease has been created but has not been claimed by a remote device.
CLAIMED The lease has been claimed by the remote device.
VERIFIED The lease has been verified on the origin device.
AUTHORIZED The lease has been authorized on the origin device and can now be used to create a session on the remote device.

If the lease_status field in the response is AUTHORIZED a session is returned in the body of the response.

Remote Sign in Session

This endpoint can take two different payloads depending on if you've gone through the lease process or if you have a refresh token. If you have a refresh token, you can simply supply that to the endpoint and don't need to create a new lease. If you do not, you need to call the Remote Sign in Lease endpoint before calling this endpoint.

Example Remote session request with lease code and nonce

curl -X POST "https://api.lootlocker.io/game/session/remote" \
  -H "LL-Version: 2021-03-01" \
  -H "Content-Type: application/json" \
  -d "{\"game_key\": \"your_game_key\", \"game_version\": \"1.0.0.0\", \"lease_code\": \"R9SJMK2R\", \"nonce\": \"01HE2TM1JWRTPCWQFBYJ538XCE\" }"

Example Remote session request with refresh token

curl -X POST "https://api.lootlocker.io/game/session/remote" \
  -H "LL-Version: 2021-03-01" \
  -H "Content-Type: application/json" \
  -d "{\"game_key\": \"your_game_key\", \"game_version\": \"1.0.0.0\", \"refresh_token\": \"v4.public.eyJ.....\" }"

Example Remote session response

{
    "lease_status": "AUTHORIZED",
    "refresh_token": "v4.public.eyJ.....",
    "session_token": "443a9adf31689ba7a6a7b2208e403b59f55c5b3e",
    "player_identifier": "01HAPG3QZXQ93KX961E6ATY35T",
    "player_id": 6936,
    "player_name": "",
    "player_ulid": "01HAPG3QZXQ93KX961E6ATY35T",
    "player_created_at": "2023-09-19T10:34:55Z",
    "public_uid": "DGK6JTPE",
    "seen_before": true,
    "check_grant_notifications": false,
    "check_deactivation_notifications": false,
    "check_dlcs": [],
    "success": true
}

Xbox Authentication

If you're developing for Xbox consoles and want to integrate with LootLocker, please reach out at hello@lootlocker.com

Player Verification

curl -X POST "https://api.lootlocker.io/game/v1/player/verify" \
  -H "Content-Type: application/json" \
  -d "{\"key\": \"your_game_key\", \"platform\": \"steam\", \"token\": 123857128391}"

If your game uses Player Verification, you need to call this endpoint before you can register a session.

The function of this endpoint is to verify the player with the platform they're currently connecting from. Some platforms require the use of player verification. Please refer to the below table.

A successful response:

{
  "success": true
}
Platform Requires Verification Note
Steam Optional
PlayStation Network Yes
iOS Not supported Deprecated, please use sign in with Apple instead
Android Not supported
Amazon Luna Not supported
Guest Login Not supported

After verifying the player, you should register a session within 5 minutes, or the token will expire, and you have to verify again.

The token parameter is different depending on which platform it is.

For Steam, you need to see the Auth documentation, under the headline Session Tickets and the Steamworks Web API, for information on how to obtain the token. Steam supports multiple Steam App IDs, through adding multiple in the LootLocker console under the Platform settings. Follow this format: 123456,234567. No spaces, and a comma as a delimintaor. You can then send along a active_steam_app_id property with the Steam App ID you wish to use for this session.

For PlayStation Network you need to supply the same auth code as when performing a purchase. An example for obtaining this code can be found in the NPAuth sample provided by Sony.

Ending A Session

LootLocker provides metrics on game session durations, which you can use to gauge user engagement. To make this information more accurate, we have a call to indicate that the game session is ending.

curl -X DELETE "https://api.lootlocker.io/game/v1/session" \
  -H "x-session-token: your_token_here"
curl -X POST "https://api.lootlocker.io/game/v1/session/end" \
  -H "x-session-token: your_token_here"

This will terminate the session on the LootLocker servers, and any further requests with this token will be rejected with a 401 Unauthorized error.

This endpoint exists both as DELETE and POST to allow for sending the sendBeacon event from browser based games.

Example response

{
  "success": true
}

Logging out from a white-label game session

If the game session was created via white label authentication, you can add the header logout: true in order to end the parent white label session token, along with any game session siblings created from that white label session.

# This logs the player out, ending both the game and white-label sessions
curl -X DELETE "https://api.lootlocker.io/game/v1/session" \
  -H "x-session-token: your_token_here" \
  -H "logout: true"

White Label Login

All white label login endpoints does not require an active session like other game API endpoints.

Instead they require a domain-key header and an optional is-development header. Before any of these endpoints are enabled, you need to first enable the white label login platform in the LootLocker console.

Sign Up

Create a new user in the white label login system.

Signing up triggers an email to the user asking to verify their account.

Input

Field Description
email Email supplied by the user
password Have to be at least 8 characters long
curl -X POST "https://api.lootlocker.io/white-label-login/sign-up" \
  -H "domain-key: 11aaa11" \
  -H "is-development: true" \
  -H "Content-Type: application/json" \
  -d "{\"email\": \"test@lootlocker.io\", \"password\": \"some password here\"}"

Example Response

{
  "id": 406,
  "game_id": 2,
  "email": "test@lootlocker.io",
  "created_at": "2021-08-25T08:03:34.612346459Z",
  "updated_at": "2021-08-25T08:03:34.612346459Z",
  "deleted_at": null,
  "validated_at": null
}

Login

After a user has been created we need to create a white label session token.

Input

Field Description
email Email supplied by the user
password Have to be at least 8 characters long
remember Start a longer session
curl -X POST "https://api.lootlocker.io/white-label-login/login" \
  -H "domain-key: 11aaa11" \
  -H "is-development: true" \
  -H "Content-Type: application/json" \
  -d "{\"email\": \"test@lootlocker.io\", \"password\": \"some password here\", \"remember\": true}"

Example Response

{
  "id": 406,
  "game_id": 2,
  "email": "test@lootlocker.io",
  "created_at": "2021-08-25T08:03:34.612346459Z",
  "updated_at": "2021-08-25T08:03:34.612346459Z",
  "deleted_at": null,
  "validated_at": null,
  "session_token": "afccd38d-09d5-48aa-8235-b9c4c9151596"
}

This token can be exchanged for a game session via the white label game session endpoint. If the game session expires, you can create a new one without prompting the user for email or password, as long as the white label token is still valid.

The token can be used to implement a "remember me" feature for the user: If the "remember" json property is true, the generated white label token lasts for up to 30 days.* Just store it locally, and reuse it to create new game sessions.

* The 30 day remember me TTL can be adjusted per game, in the White Label section of the platform settings panel.

Verify Session

Verify that a session token is still valid

Input

Field Description
token The session token retrieved from login endpoint
email Have to be at least 8 characters long
curl -X POST "https://api.lootlocker.io/white-label-login/verify-session" \
  -H "domain-key: 11aaa11" \
  -H "is-development: true" \
  -H "Content-Type: application/json" \
  -d "{\"token\": \"afccd38d-09d5-48aa-8235-b9c4c9151596\", \"email\": \"test@lootlocker.io\"}"

Example Response

{
  "game_id": 2,
  "user_id": 406,
  "email": "test@lootlocker.io"
}

Request User Verification

If the initial verification email has expired, the user can request a new verification email using this endpoint.

This can be done with either of the two parameters in the table below. If both are supplied, the user_id will be used. If none are supplied an error will be returned.

Will return HTTP 204 on success.

Input

Field Description
user_id White label login of the user. This is the ID returned when creating the user or when logging in
email The email of the user you wish to request verification for
curl -X POST "https://api.lootlocker.io/white-label-login/request-verification" \
  -H "domain-key: 11aaa11" \
  -H "is-development: true" \
  -H "Content-Type: application/json" \
  -d "{\"user_id\": 406}"

Request Reset Password

If the user needs to reset their password they can trigger a reset password email using this endpoint.

Will return HTTP 204 on success.

Input

Either of these inputs will work. If both are supplied, the user_id will be used. If none are supplied an error will be returned.

Field Description
user_id White label login of the user. This is the ID returned when creating the user or when logging in
email The email of the White Label user.
curl -X POST "https://api.lootlocker.io/white-label-login/request-reset-password" \
  -H "domain-key: 11aaa11" \
  -H "is-development: true" \
  -H "Content-Type: application/json" \
  -d "{\"email\": \"test@lootlocker.io\"}"

Delete White Label session

If you've stored the white label token, you can use this endpoint to perform a logout. This will immediately end the white label session, and any game sessions that have been spawned from it.

Input

Field Description
token Your white label session token
curl -X DELETE "https://api.lootlocker.io/white-label-login/session" \
  -H "domain-key: 11aaa11" \
  -H "is-development: true" \
  -H "Content-Type: application/json" \
  -d "{\"token\": \"afccd38d-09d5-48aa-8235-b9c4c9151596\"}"

Will return HTTP 204 on success.

If you prefer to use the game session token, the game session deletion endpoint achieves the same effect if the "logout" header is passed.

Connected Accounts

When signing in with a third party service, the user can connect their account to their existing account. This allows them to sign in with the third party service in the future.

Getting a list of connected accounts

GET /game/v1/connected-accounts

To see which accounts are connected to the current user, you can request a list of connected accounts.

Example request

curl -X "https://api.lootlocker.io/game/v1/connected-accounts" \
    -H "x-session-token: your_token_here"

Example response

{
  "connected_accounts": [
    {
      "provider": "apple",
      "provider_name": "Apple"
    },
    {
      "provider": "google",
      "provider_name": "Google"
    }
  ]
}

Connect Apple ID through REST API

PUT /game/v1/connected-accounts/apple-rest

This method of verifying a connected account uses the authorization_code from Sign in with Apple REST API.

Parameter Type Description
authorization_code string The authorization code from the Sign in with Apple REST API

Example request

curl -X PUT "https://api.lootlocker.io/game/v1/apple-rest" \
    -H "x-session-token: your_token_here" \
    -H "Content-Type: application/json" \
    -d '{"authorization_code": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.0.xxxxx.xxxxxxxx-xxxxxxxxxxxxx"}'

Example response

{
  "connected_account": {
    "provider": "apple",
    "provider_name": "Apple"
  }
}

Connect Google Account

PUT /game/v1/connected-accounts/google

This method of verifying a connected account uses the id_token from Google Sign-In for Websites.

Parameter Type Description
id_token string The id token from the Google Sign-In for Websites
client_type string Optional. Can be either web, ios, android or desktop

Example request


curl -X PUT "https://api.lootlocker.io/game/v1/connected-accounts/google" \
    -H "x-session-token: your_token_here" \
    -H "Content-Type: application/json" \
    -d '{"id_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}'

Example response

{
  "connected_account": {
    "provider": "google",
    "provider_name": "Google"
  }
}

Disconnecting an account

To disconnect an account, you need to provide the provider of the account you want to disconnect.

DELETE /game/v1/connected-accounts/{provider}

Example request

curl -X DELETE "https://api.lootlocker.io/game/v1/connected-accounts/google" \
    -H "x-session-token: your_token_here"

Player

Get Player Info

curl -X GET "https://api.lootlocker.io/game/v1/player/info" \
  -H "x-session-token: your_token_here"

This endpoint lets you get general information about the player, such as the XP, Level information and their account balance.

If your game does not have currencies enabled, account_balance will be null.

If your game does not have progression enabled, all other values will be null. level_thresholds will be null instead of an object.

Example response

{
  "success": true,
  "player_id": 12345,
  "account_balance": 0,
  "xp": 0,
  "level": 0,
  "level_thresholds": {
    "current": 0,
    "current_is_prestige": false,
    "next": 1000,
    "next_is_prestige": true
  }
}

Get Player Name

curl -X GET "https://api.lootlocker.io/game/player/name" \
  -H "x-session-token: your_token_here" \
  -H "LL-Version: 2021-03-01"

This endpoint will return the name the player has set. If no name is set, an empty property will be returned.

Example Response

{
  "name": "Player Name"
}

Lookup multiple player names using IDs

curl -G "https://api.lootlocker.io/game/player/lookup/name" \
  -H "x-session-token: your_token_here" \
  -H "LL-Version: 2021-03-01" \
  -d player_id=1 \
  -d player_id=2 \
  -d player_public_uid=JARL7PGR \
  -d player_guest_login_id=a270686a-7dd7-482f-89b6-9b2a634f46fb \
  -d steam_id=9465748036854778475 \
  -d psn_id=1234567890 \
  -d xbox_id=E51D19530BBE721286F75C03B934E5EB7CA23B99

This endpoint will return the names of the players on their last active platform.

Example Response

{
  "players": [
    {
      "player_id": 1,
      "player_public_uid": "6DDXH947",
      "name": "Player 1 Name",
      "last_active_platform": "xbox_one"
    },
    {
      "player_id": 2,
      "player_public_uid": "4FDGF738",
      "name": "Player 2 Name",
      "last_active_platform": "xbox_one"
    },
    {
      "player_id": 3,
      "player_public_uid": "JARL7PGR",
      "name": "Player 3 Name",
      "last_active_platform": "guest"
    },
    {
      "player_id": 4,
      "player_public_uid": "9HDK4F5Y",
      "name": "Player 4 PSN Name",
      "last_active_platform": "psn",
      "platform_player_id": "1234567890"
    },
    {
      "player_id": 5,
      "player_public_uid": "3XTMHFS3",
      "name": "Player 5 Steam Name",
      "last_active_platform": "steam",
      "platform_player_id": "9465748036854778475"
    },
    {
      "player_id": 6,
      "player_public_uid": "9RKPSRRT",
      "name": "Player 6 XBox Name",
      "last_active_platform": "xbox_one",
      "platform_player_id": "E51D19530BBE721286F75C03B934E5EB7CA23B99"
    },
    {
      "player_id": 7,
      "player_public_uid": "T4HV7G5D",
      "name": "Player 7 GuestLogin Name",
      "last_active_platform": "guest",
      "platform_player_id": "a270686a-7dd7-482f-89b6-9b2a634f46fb"
    }
  ]
}

Lookup multiple player 1st platform IDs using Lootlocker player IDs

curl -G "https://api.lootlocker.io/game/player/lookup/ids" \
  -H "x-session-token: your_token_here" \
  -H "LL-Version: 2021-03-01" \
  -d player_id=1 \
  -d player_id=2 \
  -d player_public_uid=JARL7PGR

This endpoint will return all known players 1st party platform id's.

Example Response

{
  "players": [
    {
      "player_id": 1,
      "player_public_uid": "6DDXH947",
      "last_active_platform": "xbox_one",
      "name": "player1",
      "platform_ids": {
        "steam": null,
        "xbox": "76561198023004363",
        "psn": null
      }
    },
    {
      "player_id": 2,
      "player_public_uid": "4FDGF738",
      "last_active_platform": "steam",
      "name": "player2",
      "platform_ids": {
        "steam": 9223372036854775807,
        "xbox": null,
        "psn": null
      }
    },
    {
      "player_id": 3,
      "player_public_uid": "JARL7PGR",
      "last_active_platform": "psn",
      "name": "player3",
      "platform_ids": {
        "steam": 76561198023004363,
        "xbox": null,
        "psn": 1234567890
      }
    }
  ]
}

Set Player Name

curl -X PATCH "https://api.lootlocker.io/game/player/name" \
  -H "x-session-token: your_token_here" \
  -H "LL-Version: 2021-03-01" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"Player Name\"}"

This endpoint will let the player set a name, and return that name on success.

The max length of a name is 255 characters.

Example Response

{
  "name": "Player Name"
}

Get Inventory List

curl -X GET "https://api.lootlocker.io/game/v1/player/inventory/list" \
  -H "x-session-token: your_token_here"

See the Get Inventory Stream endpoint for explanations of the properties in the response objects.

This call offers a paginated list of the players inventory. There are two URL parameters you can use to affect the offset of asset instances returned. after is the highest instance_id returned from the previous call, and it's used to fetch the next page. count is an optional parameter which is the max number of items returned. It defaults to 50, but can be set as high as 200. Anything above 200 will be ignored and the default value used instead.

When using this endpoint, universal assets are not returned as part of the players inventory, and as such you also need to implement the Get Universal Assets endpoint. If you use the streaming inventory endpoint, this is not necessary as universal assets are returned.

Example response object

{
    "success": true,
    "inventory": [
        {
            "instance_id": 538,
            "variation_id": 45,
            "rental_option_id": null,
            "acquisition_source": "grant_default_loadout",
            "acquisition_date": "2022-05-30T07:57:58+00:00",
            "asset": {...},
            "rental": {
                "is_rental": false,
                "time_left": null,
                "duration": null,
                "is_active": null
            }
        }
    ]
}

Get Inventory Stream

curl -X GET "https://api.lootlocker.io/game/v1/player/inventory" \
  -H "x-session-token: your_token_here"

Example response object

{
    "instance_id": 538,
    "variation_id": 45,
    "rental_option_id": null,
    "acquisition_source": "grant_default_loadout",
    "acquisition_date": "2022-05-30T07:57:58+00:00",
    "asset": {...},
    "rental": {
        "is_rental": false,
        "time_left": null,
        "duration": null,
        "is_active": null
    }
}

This endpoint will return to you all the assets that the player currently owns, as a streaming response, similar to the assets call. The root object will however contain 2 properties, one being instance_id and the other being asset. The asset will be holding the asset object exactly the same way as any other asset - Referenced as "asset": {...} in the example.

If a player owns multiple of the same asset, it will be there multiple times.

If this endpoint is used instead of the Get Inventory List call, you do not need to implement the Get Universal Assets call as those assets are already returned in this response.

Note the rental object. This contains information regarding rental assets. The is_rental property will let you know if the asset is a rental or not, if it isn't you can safely ignore the other parameters in the object. time_left and duration are denoted in seconds, and active lets you know if the rental has been activated and is thus currently active, or if it is waiting to be activated. Expired rentals are not returned. Beware that the time_left property can be negative if you request the inventory after the instance is expired, but it has not yet been expired by LootLocker.

The acquisition_source property will let you know how a player got to own the current instance of the asset. See the below table for all the different ways players can acquire asset instances.

Source Meaning
grant_default_loadout This was part of the games default loadout when the player got it
grant_universal_asset This was a universal asset that the player used, and thus got an instance of
grant_dlc This was granted by using the dlc migration functionality
reward_event This was rewarded as a reward for getting a medal in an event
reward_trigger This was rewarded by the trigger functionality
reward_level_up This was rewarded because the player levelled up
purchase_package This was part of a package the player purchased
purchase_unit This was a single asset the player purchased
steam_command This was a command sent from steam, creating the asset
rent_unit This is a rented asset
reward_collectable This was rewarded through completing a collectable criteria
grant_loot_box This asset was granted from opening a Loot Box

Grant An Asset To The Player

curl -X POST "https://api.lootlocker.io/game/player/inventory/grant" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d "{\"asset_id\": 2, \"asset_variation_id\": 3, \"asset_rental_option_id\": 4"}

This endpoint will grant an asset to a player.

Example Response

{
    "id": 1,
    "asset_id": 2,
    "asset_variation_id": 3,
    "asset_rental_option_id": 4,
    "asset_ulid": "01HFCET3F2M917CPD4DT45089W",
    "acquisition_source": "grant_game_api",
    "acquisition_date": "2023-11-24T16:12:41Z"
}

Remove An Asset From The Player Inventory

curl -X DELETE "https://api.lootlocker.io/game/player/inventory/{asset_instance_id}" \
  -H "x-session-token: your_token_here" \

This endpoint will remove an asset from the player's inventory. You will need the instance_id which can be fetched using the Get Inventory endpoint.

Example Response

This endpoint will not have a body, being a 204 No Content HTTP response.

Get Universal Assets

curl -X GET "https://api.lootlocker.io/game/v1/player/inventory/universal" \
  -H "x-session-token: your_token_here"

You only need to implement this endpoint if you use the List inventory call. If you have implemented the streaming inventory call, you can ignore this.

This call offers a paginated list of the games universal assets. There are two URL parameters you can use to affect the offset of assets returned. after is the highest universal_id returned from the previous call, and it's used to fetch the next page. For the first call you can either set this parameter to 0 or skip it. count is an optional parameter which is the max number of items returned. It defaults to 50, but can be set as high as 200. Anything above 200 will be ignored and the default value used instead.

Example response

{
    "success": true,
    "global_assets": [
        {
            "universal_id": 323,
            "variation_id": null,
            "rental_option_id": null,
            "acquisition_source": "grant_universal_asset",
            "asset": {...},
            "rental": {
                "is_rental": false,
                "time_left": null,
                "duration": null,
                "is_active": null
            }
        }
    ]
}

Get Currency Balance

curl -X GET "https://api.lootlocker.io/game/v1/player/balance" \
  -H "x-session-token: your_token_here"

This endpoint will return the amount of credits the current player have on their account.

Example response

{
  "success": true,
  "balance": 0
}

Submit XP

curl -X POST "https://api.lootlocker.io/game/v1/player/xp" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d "{\"points\": 100}"

This endpoint will receive xp, and award it to the player. The response will hold information about the players current xp and level.

Example response

{
  "success": true,
  "xp": {
    "previous": 0,
    "current": 50
  },
  "levels": [
    {
      "level": 0,
      "xp_threshold": 0
    },
    {
      "level": 1,
      "xp_threshold": 100
    },
    {
      "level": 2,
      "xp_threshold": 200
    }
  ],
  "check_grant_notifications": false
}

The levels array in the response holds level information about the current level (the first object), and the at least the two next, for displaying progress on the client side. In case of a user skipping all the way from level 0 to level 3, you would see 3 additional levels returned in the response.

Example response where assets have been granted

{
  "success": true,
  "xp": {
    "before": 0,
    "current": 50
  },
  "levels": [
    {
      "level": 0,
      "xp_threshold": 0
    },
    {
      "level": 1,
      "xp_threshold": 100
    },
    {
      "level": 2,
      "xp_threshold": 200
    }
  ],
  "check_grant_notifications": true
}

The check_grant_notifications option means that the player has been granted assets with this score submission. In this case you should issue a request to the Player Asset Notifications call immediately, unlike the Session Registration call where you have to wait.

Example error because the game does not use XP

{
  "success": false,
  "error": "Game does not use XP"
}

Get Other Players XP And Level

curl -X GET "https://api.lootlocker.io/game/v1/player/score/76561198023004363?platform=steam" \
  -H "x-session-token: your_token_here"

Example response

{
  "success": true,
  "xp": 57185,
  "level": 8
}

The platform parameter is optional. If you do not supply one, the backend is gonna default to the same one as the current player is on.

If the player does not exists, you will get a faulty response with the error field set to "Unknown player".

Get Multiple Other Players XP And Level

curl -X POST "https://api.lootlocker.io/game/v1/player/scores" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d "{\"platform\": \"steam\", \"player_ids\": [ \"76561198023004363\" ]}"

Example response

{
  "success": true,
  "players": [
    {
      "id": "76561198023004369",
      "xp": null,
      "level": 6
    }
  ]
}

Player Asset Notifications

curl -X GET "https://api.lootlocker.io/game/v1/player/notification/assets" \
  -H "x-session-token: your_token_here"

Example response

{
  "success": true,
  "objects": [
    {
      "instance_id": 5713,
      "variation_id": 28,
      "acquisition_source": "reward_level_up",
      "asset": {
        "id": 16,
        "name": "Founder Gloves",
        "active": true,
        "price": 0,
        "sales_price": null,
        "display_price": "0",
        "shop_thumbnail": "CharacterAttachments/Item Thumbnails/Hands/poppermost/thumb_poppermost-founder.tif",
        "context": "Arms",
        "context_id": 1,
        "detachable": true,
        "updated": "Fri, 20 Feb 2015 21:53:36 +0000",
        "default_variation_id": 28,
        "default_loadouts": {
          "skier": true,
          "snowboarder": false
        },
        "unique_instance": false,
        "external_identifiers": {
          "psn": {
            "entitlement_id": "CRED01",
            "service_label": 1
          }
        },
        "description": "",
        "variations": [
          {
            "id": 28,
            "name": "poppermost-founder",
            "properties": [
              {
                "material_path": "CharacterAttachments/Hands/poppermost/poppermost-founder/poppermost-founder.mtl",
                "binding_path": "CharacterAttachments/hands/shared-meshes/gloves-a/gloves-a.skin",
                "bone_id": 12,
                "bone_overrides": {}
              }
            ]
          }
        ],
        "filters": [
          {
            "value": "Poppermost",
            "name": "Brand",
            "url": null
          },
          {
            "value": "13/14",
            "name": "Season",
            "url": null
          }
        ],
        "package_contents": null,
        "storage": [
          {
            "key": "dog",
            "value": "yes"
          }
        ],
        "files": ["https://cdn.lootlocker.io/141/5f230b1e14614.txt"],
        "data_entities": ["Your games custom data for this asset"]
      }
    }
  ]
}

This endpoint can be called to get assets that have been granted (given to) the player since the last time this endpoint was called. The backend will automatically keep track of when it was last called and thus only return valid information. In case no assets has been granted, the array will be empty.

For information on the acquisition_source parameter, see Get Inventory.

Player Asset Deactivation Notifications

curl -X GET "https://api.lootlocker.io/game/v1/player/notification/deactivations" \
  -H "x-session-token: your_token_here"

This endpoint will return deactivations since the last time it's been checked. Do not expect both replacement_asset_id and reason to have values at the same time. They can have, but it is not required.

Example response

{
  "success": true,
  "objects": [
    {
      "deactivated_asset_id": 4,
      "replacement_asset_id": 5,
      "reason": "Here is a good reason for deactivating this asset."
    }
  ]
}

Initiate DLC Migration

curl -X POST "https://api.lootlocker.io/game/v1/player/dlcs" \
  -H "x-session-token: your_token_here"

This endpoint will initiate a DLC migration for the current player. 5 minutes after calling this endpoint you should issue a call to the Player Asset Notifications call, to get the results of the migration, if any.

Example response

{
  "success": true
}

Get DLCs Migrated

curl -X GET "https://api.lootlocker.io/game/v1/player/dlcs" \
  -H "x-session-token: your_token_here"

This endpoint will return a list of DLC's migrated for the player. The DLC identifiers returned will be the ones of the platform the DLC belongs to. The identifier will always be a string, even if the identifier is numeric.

Example response

{
  "success": true,
  "dlcs": ["257300", "257301", "257302", "433770"]
}

Set Profile Private

curl -X DELETE "https://api.lootlocker.io/game/v1/player/profile/public" \
  -H "x-session-token: your_token_here"

This endpoint will set the players profile to private. This means that their inventory will not be displayed publicly on Steam and other places.

Example response

{
  "success": true
}

Set Profile Public

curl -X POST "https://api.lootlocker.io/game/v1/player/profile/public" \
  -H "x-session-token: your_token_here"

This endpoint will set the players profile to public. This means that their inventory will be displayed publicly on Steam and other places.

Example response

{
  "success": true
}

Delete Player

curl -X DELETE "https://api.lootlocker.io/game/player" \
  -H "x-session-token: your_token_here"

This endpoint will mark the player for deletion. After 30 days the player will be deleted from the system.

Will return HTTP 204 on success.

Player Files

Player Files is a feature where you can store files for players in LootLocker's storage system, where they will then be distributed through our CDN for fast retrieval by your players. This feature can be used for any files you wish to save to LootLocker in a players scope, such as Cloud Saves, Avatars or any other reason you can come up with.

Limitations

There are two limitations on Player Files:

Upload a File

curl -X POST "https://api.lootlocker.io/game/player/files" \
  -H "x-session-token: your_token_here" \
  -H "LL-Version: 2021-03-01" \
  -F 'file=@"path/to/your/file"' \
  -F 'purpose="save_game"' \
  -F 'is_public="false"'

Use this endpoint to upload a file to a players file storage.

Use the purpose property to tag what the purpose of the file is. This string will be uppercased in responses, to avoid issues with casing when you compare strings. If no purpose is provided, the default will be PLAYER_FILE.

Successful upload example response

{
  "id": 318,
  "revision_id": "01GPNZHCVEF6F0QGA3V2B7CN44",
  "name": "save_game_1.zip",
  "size": 7056,
  "purpose": "SAVE_GAME_SLOT_1",
  "public": false,
  "url": "https://cdn.lootlocker.io/2/892/oJnNPGsiuzytMOJPatwtPilfsfykSBGp.jpg?Expires=1635366031&Signature=Z7MG~WgUyqpBNlXRePXxuV2uFbI0fEkAa3chk-3YO2XlWyd1veSl5V2dmFyVM1CndY6cfHo9ds3ilthwY~NjUiFmrx6ycfG3GJ5Z~kqzuyyMpH~LXTh~tIwnZpJpKScFUeBz5PpkSQPfOo4nuWktQBmpIgOhLlD2cWKOlQllBaIhjFvUh1HGIs-1u2-DiX9eDIgBDYzP4k0aMGH0aKjKF8Wb1jbAwaAcvQBeiPC~B~DgjlsHy6UjS59nYLCI-3EMheivk7H5-z-R65Au8VGg1koP89QtEjViy2HKbMKId~tQ3-cJg-ylRGHbE7jGlRyFC9CQLfeJXqx-IgaKfjVZCQ__&Key-Pair-Id=APKAIIBA3IODTCVA4BKQ",
  "url_expires_at": "2021-10-27T20:20:31.433987069Z",
  "created_at": "2021-10-27T14:20:31.428496822Z"
}

The url_expires_at timestamp will let you know when you need to renew the URL for the download to work. URL's are valid for 6 hours after uploading, or using any endpoint that returns the files.

Exceeded file size example response

{
  "message": "file too large",
  "request_id": "req_6eb044d0-5b1e-45cc-8651-f72b3ee44985"
}

If you exceed the file size limit you will get a 413 Request Entity Too Large error back from the API, with the payload in the example.

Too many files example response

{
  "message": "max allowed file count reached",
  "request_id": "req_6eb044d0-5b1e-45cc-8651-f72b3ee44985"
}

If you exceed the file count limit you will get a 400 Bad Request error back from the API, with the payload in the example.

Update a File

curl -X PUT 'https://api.lootlocker.io/game/player/files/:file_id' \
  -H "x-session-token: your_token_here" \
  -H "LL-Version: 2021-03-01"
  -F 'file=@"path/to/your/file"'

Use this endpoint to update a file, updating a file will create a new revision of that file, the system will keep last 5 revisions.

Successful upload example response

{
  "id": 318,
  "revision_id": "01GPNZHCVEF6F0QGA3V2B7CN44",
  "name": "save_game_1.zip",
  "size": 7056,
  "purpose": "SAVE_GAME",
  "public": false,
  "url": "https://cdn.lootlocker.io/2/892/oJnNPGsiuzytMOJPatwtPilfsfykSBGp.jpg?Expires=1635366031&Signature=Z7MG~WgUyqpBNlXRePXxuV2uFbI0fEkAa3chk-3YO2XlWyd1veSl5V2dmFyVM1CndY6cfHo9ds3ilthwY~NjUiFmrx6ycfG3GJ5Z~kqzuyyMpH~LXTh~tIwnZpJpKScFUeBz5PpkSQPfOo4nuWktQBmpIgOhLlD2cWKOlQllBaIhjFvUh1HGIs-1u2-DiX9eDIgBDYzP4k0aMGH0aKjKF8Wb1jbAwaAcvQBeiPC~B~DgjlsHy6UjS59nYLCI-3EMheivk7H5-z-R65Au8VGg1koP89QtEjViy2HKbMKId~tQ3-cJg-ylRGHbE7jGlRyFC9CQLfeJXqx-IgaKfjVZCQ__&Key-Pair-Id=APKAIIBA3IODTCVA4BKQ",
  "url_expires_at": "2021-10-27T20:20:31.433987069Z",
  "created_at": "2021-10-27T14:20:31.428496822Z"
}

The url_expires_at timestamp will let you know when you need to renew the URL for the download to work. URL's are valid for 6 hours after uploading, or using any endpoint that returns the files.

Exceeded file size example response

{
  "message": "file too large",
  "request_id": "req_6eb044d0-5b1e-45cc-8651-f72b3ee44985"
}

List Files

curl -X GET "https://api.lootlocker.io/game/player/files" \
  -H "x-session-token: your_token_here" \
  -H "LL-Version: 2021-03-01"

Use this endpoint for listing the files that your currently active player own.

The url_expires_at timestamp will let you know when you need to renew the URL for the download to work. URL's are valid for 6 hours after uploading, or using any endpoint that returns the files.

Example Response

{
  "items": [
    {
      "id": 318,
      "revision_id": "01GPNZHCVEF6F0QGA3V2B7CN44",
      "name": "smol.jpg",
      "size": 7056,
      "purpose": "SAVE_GAME",
      "public": false,
      "url": "https://cdn.lootlocker.io/2/892/oJnNPGsiuzytMOJPatwtPilfsfykSBGp.jpg?Expires=1635369933&Signature=Wp-PUZdoh3XdqQNOnPP80-q81ftGpLVJ3oub3RajnfjaP15rHzVWCCJ8e8lzpzrzdilu1gxoTiK1NT7iZayJXV~1XvcagCbkLCsrLkHlDZ0ms17C1YL5iNu1crBCJOhOhpwhknDmgt95NWa2GjLydylj7-0mqjALoURAMzpWvmbXUClUhtzIgGsBIEn2jy~syplWtMstTHE13EHmsxqfbAr8fkp91JGHaLFqSJL5YvlnIe5WoVNeBII8tjBb6YtEEF2dyliLyJOk8RaGtCDodKMmwOlwAlw-~lyfPrUOxH62c87-vkn8~uPQgAxcX0kp6NDudFrO5uiyESyOymIscw__&Key-Pair-Id=APKAIIBA3IODTCVA4BKQ",
      "url_expires_at": "2021-10-27T21:25:33.339117882Z",
      "created_at": "2021-10-27T14:20:31Z"
    }
  ]
}

List Another Players Public Files

curl -X GET "https://api.lootlocker.io/game/player/{player_id}/files" \
  -H "x-session-token: your_token_here" \
  -H "LL-Version: 2021-03-01"

This endpoint can be used to list and retrieve another players public files.

Example Response

{
  "items": [
    {
      "id": 5318,
      "revision_id": "01GPNZHCVEF6F0QGA3V2B7CN44",
      "name": "world.jpg",
      "size": 7056,
      "purpose": "WORLD",
      "public": true,
      "url": "https://cdn.lootlocker.io/2/892/oJnNPGsiuzytMOJPatwtPilfsfykSBGp.jpg?Expires=1635369933&Signature=Wp-PUZdoh3XdqQNOnPP80-q81ftGpLVJ3oub3RajnfjaP15rHzVWCCJ8e8lzpzrzdilu1gxoTiK1NT7iZayJXV~1XvcagCbkLCsrLkHlDZ0ms17C1YL5iNu1crBCJOhOhpwhknDmgt95NWa2GjLydylj7-0mqjALoURAMzpWvmbXUClUhtzIgGsBIEn2jy~syplWtMstTHE13EHmsxqfbAr8fkp91JGHaLFqSJL5YvlnIe5WoVNeBII8tjBb6YtEEF2dyliLyJOk8RaGtCDodKMmwOlwAlw-~lyfPrUOxH62c87-vkn8~uPQgAxcX0kp6NDudFrO5uiyESyOymIscw__&Key-Pair-Id=APKAIIBA3IODTCVA4BKQ",
      "url_expires_at": "2022-06-27T21:25:33.339117882Z",
      "created_at": "2022-06-27T14:20:31Z"
    }
  ]
}

Get Single File

curl -X GET "https://api.lootlocker.io/game/player/files/{file_id}" \
  -H "x-session-token: your_token_here" \
  -H "LL-Version: 2021-03-01"

This endpoint requires a parameter in the URL, holding the ID of the file you wish to obtain. You will get the ID of files when you upload them, or call the list endpoint.

The url_expires_at timestamp will let you know when you need to renew the URL for the download to work. URL's are valid for 6 hours after uploading, or using any endpoint that returns the files.

Example Response

{
  "id": 318,
  "revision_id": "01GPNZHCVEF6F0QGA3V2B7CN44",
  "name": "smol.jpg",
  "size": 7056,
  "purpose": "SAVE_GAME",
  "public": false,
  "url": "https://cdn.lootlocker.io/2/892/oJnNPGsiuzytMOJPatwtPilfsfykSBGp.jpg?Expires=1635370000&Signature=JKJTvRoZpxgtebwCqtuADp-mH4j958vxo29LvRtWv~VC4iSfQHw5S8YFMVPMiWSJ3s-RY2V5VWBt1njWAjq~4fzDwSVXp6h0a5rPmG0oYa6~BId~sz8Blab2PCPkUMeYkLRG5EsnQyDHwPdHgIVAgZb5fwyVuKldmyQnbqeeHj9DmyoP8AmUsH6OJ63GQw2GkjRhw0x9B3jfn079LdqH0fVX80-UIfv7FRT-gt9fINsBT3ujy5~GoP91mJwPh6EV9xbQmZvAI4j0~5adP4mD01zYum3SARXqPdtax9MWiC42Ad-ADQQje3hsuimaDlhIgELfFhRG1il3FEcNCdw4aA__&Key-Pair-Id=APKAIIBA3IODTCVA4BKQ",
  "url_expires_at": "2021-10-27T21:26:40.407880449Z",
  "created_at": "2021-10-27T14:20:31Z"
}

Delete File

curl -X DELETE "https://api.lootlocker.io/game/player/files/{file_id}" \
  -H "x-session-token: your_token_here" \
  -H "LL-Version: 2021-03-01"

If you need to delete a file, this endpoint will allow you to do that.

This endpoint requires a parameter in the URL, holding the ID of the file you wish to obtain. You will get the ID of files when you upload them, or call the list endpoint.

This endpoint will not have a body, being a 204 No Content HTTP response.

The file will be deleted immediately and the action can not be reversed.

Player Progressions

Player progression API is used to track your player's progress on your game's progressions.

You can also add or subtract points, reset or delete player's progressions using this API.

Starting a player on a progression is as easy as just starting to add points to it.

Get Player Progressions

curl -X GET "https://api.lootlocker.io/game/player/progressions?count=10&after=01GJN6J46DM00Z88WR225Y9P77"
-H "x-session-token: your_token_here"

Get list of progressions the player is currently on. Results are always sorted by ID.

URL Structure

/game/player/progressions

Example Response

{
  "pagination": {
    "next_cursor": null,
    "previous_cursor": null,
    "total": 2
  },
  "items": [
  {
    "id": "01GJN6J46DM00Z88WR225Y9P77",
    "progression_key": "fighter",
    "progression_name": "Fighter",
    "step": 1,
    "points": 200,
    "previous_threshold": 0,
    "next_threshold": 500,
    "last_level_up": null
  },
  {
    "id": "01GJN6JGK3AV0N8YJ9GHSCJ4D3",
    "progression_key": "mage",
    "progression_name": "Mage",
    "step": 3,
    "points": 1300,
    "previous_threshold": 1000,
    "next_threshold": 2000,
    "last_level_up": "2022-11-24T16:12:41Z"
  }
  ]
}

Query Parameters:

Field Description
after Cursor for pagination, a cursor will be returned in the response
count Number of progressions returned per page. Max 500 is allowed

Get Player Progression By Key

curl -X GET "https://api.lootlocker.io/game/player/progressions/fighter"
-H "x-session-token: your_token_here"

Get a single player progression by Key.

URL Structure

/game/player/progressions/<progression_key>

Example Response

{
  "id": "01GJN6J46DM00Z88WR225Y9P77",
  "progression_key": "fighter",
  "progression_name": "Fighter",
  "step": 1,
  "points": 200,
  "previous_threshold": 0,
  "next_threshold": 500,
  "last_level_up": null
}

URL Parts

Part Description
progression_key Key of the progression

Add points to a player progression

curl -X POST "https://api.lootlocker.io/game/player/progressions/fighter/points/add" \
-H "x-session-token: your_token_here" \
-H "Content-Type: application/json" \
-d "{\"amount\": 1000 }"

Adds specified amount of points to a player progression. If the player is not on that progression it will be automatically started.

If the player leveled up, awarded_tiers fields will contain acquired rewards.

URL Structure

/game/player/progressions/<progression_key>/points/add

Example Response

{
  "id": "01GJN6J46DM00Z88WR225Y9P77",
  "progression_key": "fighter",
  "progression_name": "Fighter",
  "step": 3,
  "points": 1200,
  "previous_threshold": 1000,
  "next_threshold": 2000,
  "last_level_up": "2022-11-24T16:12:41Z",
  "awarded_tiers": [
    {
      "step": 2,
      "points_threshold": 500,
      "rewards": {
        "progression_points_rewards": [
          {
            "progression_key": "blacksmithing",
            "progression_name": "Blacksmithing",
            "amount": 100
          }
        ],
        "progression_reset_rewards": [
          {
            "progression_key": "death_penalty_stacks",
            "progression_name": "Death penalty stacks"
          }
        ],
        "asset_rewards": [
          {
            "asset_id": 2,
            "asset_variation_id": null,
            "asset_rental_option_id": null
          }
        ],
        "currency_rewards": [
          {
            "currency_name": "Gold",
            "currency_code": "GLD",
            "amount": "100"
          }
        ]
      }
    },
    {
      "step": 3,
      "points_threshold": 1000,
      "rewards": {
        "progression_points_rewards": [],
        "progression_reset_rewards": [],
        "asset_rewards": [],
        "currency_rewards": []
      }
    }
  ]
}

URL Parts

Part Description
progression_key Key of the progression

Available input fields

amount is required.

Field Description
amount Amount of points to be added to the player's progression.

Subtract points from a player progression

curl -X POST "https://api.lootlocker.io/game/player/progressions/mage/points/subtract" \
-H "x-session-token: your_token_here" \
-H "Content-Type: application/json" \
-d "{\"amount\": 10 }"

Subtracts specified amount of points from a player progression. The player cannot go down a progression step, the points will be set to the previous_threshold if too many points are being subtracted.

URL Structure

/game/player/progressions/<progression_key>/points/subtract

Example Response

{
    "id": "01GJN6JGK3AV0N8YJ9GHSCJ4D3",
    "progression_key": "mage",
    "progression_name": "Mage",
    "step": 3,
    "points": 1290,
    "previous_threshold": 1000,
    "next_threshold": 2000,
    "last_level_up": "2022-11-24T16:12:41Z",
    "awarded_tiers": []
}

URL Parts

Part Description
progression_key Key of the progression

Available input fields

amount is required.

Field Description
amount Amount of points to be subtracted from the player's progression.

Reset a player progression

curl -X POST "https://api.lootlocker.io/game/player/progressions/mage/reset" \
-H "x-session-token: your_token_here"

Resets a player progression. This endpoint sets the player progression points to 0, so it still shows up as an active progression.

URL Structure

/game/player/progressions/<progression_key>/reset

Example Response

{
    "id": "01GJN6JGK3AV0N8YJ9GHSCJ4D3",
    "progression_key": "mage",
    "progression_name": "Mage",
    "step": 1,
    "points": 0,
    "previous_threshold": 0,
    "next_threshold": 1000,
    "last_level_up": null,
    "awarded_tiers": []
}

URL Parts

Part Description
progression_key Key of the progression

Delete a player progression

curl -X DELETE "https://api.lootlocker.io/game/player/progressions/mage" \
-H "x-session-token: your_token_here"

Deletes a player progression. It won't show up in player's active progression list.

URL Structure

/game/player/progressions/<progression_key>

Example Response

This endpoint will not have a body, being a 204 No Content HTTP response.

URL Parts

Part Description
progression_key Key of the progression

Feedback

Create report

curl -X POST --location 'https://api.lootlocker.io/game/feedback' \
-H 'x-session-token: {x-session-token}' \
-H 'Content-Type: application/json' \
-d '{
    "entity": "player",
    "entity_id": "01J0RCFNHHN3CFT76EDASDYDZ9",
    "category_id": "01J0RCG7V14NNVM20CBT9FX271",
    "description": "This guy hacking!"
}`

Response Status 204 - No content

HTTP Request

POST https://api.lootlocker.io/game/feedback

Parameters

Parameter Type Description
entity string required One of player, ugc or game.
entity_id string required The ULID of the entity to report.
category_id string required The ULID of the category.
description string required The description of the report.

List Categories

curl -X GET --location 'https://api.lootlocker.io/game/feedback/entity/{entity}' \
-H 'x-session-token: {x-session-token}' \
-H 'Content-Type: application/json' \
-d '{
    "entity": "player",
    "entity_id": "01J0RCFNHHN3CFT76EDASDYDZ9",
    "category_id": "01J0RCG7V14NNVM20CBT9FX271",
    "description": "This guy hacking!"
}`

Response Status 200

{
    "categories": [
        {
            "id": "01J2BSSGN0J5S16H3JWDMQ2FGC",
            "game_id": 2,
            "entity": "player",
            "name": "Griefing",
            "description": "Use this to report griefing players",
            "created_at": "2024-07-09T13:09:11Z",
            "updated_at": null,
            "deleted_at": null
        },
        {
            "id": "01J2BGJWHV9N6XA5B1TEM37936",
            "game_id": 2,
            "entity": "player",
            "name": "Hacking",
            "description": "Use this to report hacking players",
            "created_at": "2024-07-09T10:28:17Z",
            "updated_at": null,
            "deleted_at": null
        },
        {
            "id": "01J2BGNCZEHDCBKY21GZCX52QV",
            "game_id": 2,
            "entity": "player",
            "name": "Spamming",
            "description": "Use this to report spamming players",
            "created_at": "2024-07-09T10:29:39Z",
            "updated_at": null,
            "deleted_at": null
        }
    ]
}

HTTP Request

GET https://api.lootlocker.io/game/feedback/entity/{entity}

Parameters

Parameter Type Description
entity string required One of player, ugc or game.

Characters

Create Character

curl -X POST "https://api.lootlocker.io/game/v1/player/character" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d "{\"character_type_id\": 1, \"is_default\": true, \"name\": \"Crazy Monday Chimp\"}"

When creating a character there is only one required field: character_type_id. See List Character Types to get your games Character Types. The other parameters are optional and are the same as for the Update Character call.

Example Response

{
    "success": true,
    "loadouts": [
        {
            "character": {
                "id": 6171,
                "type": "Heavy Vehicle",
                "name": "Crazy Monday Chimp",
                "is_default": true
            },
            "loadout": [
                {
                    "variation_id": 1294,
                    "instance_id": 170657,
                    "mounted_at": "2015-07-24T12:58:08+0000",
                    "asset": {...},
                    "rental": {
                        "is_rental": false,
                        "time_left": null,
                        "duration": null,
                        "is_active": null
                    }
                }
            ]
        }
    ]
}

Update Character

curl -X PUT "https://api.lootlocker.io/game/v1/player/character/6171" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d "{\"is_default\": true, \"name\": \"Crazy Monday Chimp\"}"

This endpoint lets you set a character as default, and set the name of the character. None of the parameters are required.

Since changing the default status of a character will also change other characters on the player, the response will be identical to that from the Character Loadouts api call.

The only restraint on the name field is that it can be no longer than 255 characters.

List Character Types

curl -X GET "https://api.lootlocker.io/game/v1/player/character/types" \
  -H "x-session-token: your_token_here"

Call this endpoint to list the character types configured for your game. If you have any key/value storage associated with your Character Type, it'll be returned here. Otherwise it will be an empty array. Default loadout for the character type is also returned if it exists. If it does not exist it is null.

Example Response

{
  "success": true,
  "character_types": [
    {
      "id": 1,
      "is_default": true,
      "name": "Heavy Vehicle",
      "storage": [
        {
          "key": "custom_data",
          "value": "value"
        }
      ],
      "default_loadout": [
        {
          "Asset": "information in same format as in the asset calls."
        }
      ]
    }
  ]
}

List Player Characters

curl -X GET "https://api.lootlocker.io/game/v1/player/character/list" \
  -H "x-session-token: your_token_here"

This endpoint is used to list characters to a player. If your game uses heroes the characters underlying the heroes will be listed too.

Example Response

{
    "items": [
        {
            "id": 22,
            "default": true,
            "name": "Quick Wheels"
        }
    ]
}

Character Loadouts

curl -X GET "https://api.lootlocker.io/game/v1/player/character/loadout" \
  -H "x-session-token: your_token_here"

This call will return all characters loadouts for a game, and have some additional information on the characters.

Note the rental object. This contains information regarding rental assets. The is_rental property will let you know if the asset is a rental or not, if it isn't you can safely ignore the other parameters in the object. time_left and duration are denoted in seconds, and active lets you know if the rental has been activated and is thus currently active, or if it is waiting to be activated. Expired rentals are not returned. Beware that the time_left property can be negative if you request the inventory after the instance is expired, but it has not yet been expired by LootLocker.

Successful request (truncated for brevity)

{
    "success": true,
    "loadouts": [
        {
            "character": {
                "id": 6171,
                "type": "Heavy Vehicle",
                "name": "Crazy Monday Chimp",
                "is_default": true
            },
            "loadout": [
                {
                    "variation_id": 1294,
                    "instance_id": 170657,
                    "mounted_at": "2015-07-24T12:58:08+0000",
                    "asset": {...},
                    "rental": {
                        "is_rental": false,
                        "time_left": null,
                        "duration": null,
                        "is_active": null
                    }
                }
            ]
        }
    ]
}

Get Other Players Character Loadouts By Platform Identifier

curl -X GET "https://api.lootlocker.io/game/v1/player/character/loadout/76561198023004363?platform=steam" \
  -H "x-session-token: your_token_here"

This call will return all characters loadouts for a game, and have some additional information on the characters.

The response from this endpoint will be identical to the one from the Character Loadouts api call.

Equip Asset to Default Character

curl -X POST "https://api.lootlocker.io/game/v1/player/equip" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d "{\"instance_id\": 35}"

Equipping an asset lets the backend know what the current loadout of a player is, which can then be reported back to other players, used for synchronising across multiple platform, be used to create a profile page, or.. You get the picture.

The ID in this URL is the instance_id that will be returned from the inventory and loadout calls.

When equipping an asset, you will get the full list of equipped assets back in the response (see Get current loadout). This should be treated as the universal truth, and the loadout in the game should reflect this.

Equipping a global asset

curl -X POST "https://api.lootlocker.io/game/v1/player/equip" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d "{\"asset_id\": 35, \"asset_variation_id\": 66}"

When you want to equip a global asset, it requires the asset_id and an asset_variation_id, which will then create an instance that will be returned just like when equipping with an instance_id.

If you are using the global asset equip syntax on an asset that is not global, you will get a response with success set to false, and a suiting error message.

Equip Asset to Character By Id

curl -X POST "https://api.lootlocker.io/game/v1/player/character/12765/equip" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d "{\"instance_id\": 35}"

This endpoint allows you to equip an asset to a character by id.

Just like you can equip a global asset to the default character, you can do the same for this endpoint.

You can obtain the character id from the Characters Loadouts call.

curl -X POST "https://api.lootlocker.io/game/v1/player/character/12765/equip" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d "{\"asset_id\": 35, \"asset_variation_id\": 66}"

Successful request (truncated for brevity)

{
  "success": true,
  "character": {
    "id": 6171,
    "type": "Heavy Vehicle",
    "name": "Crazy Monday Monkey",
    "is_default": true
  },
  "loadout": [
    {
      "variation_id": 1271,
      "instance_id": 170658,
      "mounted_at": "2015-07-24T12:58:08+0000",
      "asset": {
        "Asset": "information in same format as in the asset calls."
      }
    }
  ]
}

Unequip Asset to Default Character

curl -X DELETE "https://api.lootlocker.io/game/v1/player/equip/1" \
  -H "x-session-token: your_token_here"

Unequipping does the opposite of equipping. For the same reasons. The integer at the end is also the instance_id here.

When un-equipping an asset, you will get the full list of equipped assets back in the response (see Get current loadout). This should be treated as the universal truth, and the loadout in the game should reflect this.

Non successful request because no such instance exists. Status code: 404

{
  "success": false,
  "error": "No such instance"
}

Unequip Asset To Character By Id

curl -X DELETE "https://api.lootlocker.io/game/v1/player/character/6171/equip/170657" \
  -H "x-session-token: your_token_here"

This endpoint lets you unequip assets from a character. The response will return the loadout for this character.

Successful request (truncated for brevity)

{
    "success": true,
    "character": {
        "id": 6171,
        "type": "Heavy Vehicle",
        "name": "Crazy Monday Monkey",
        "is_default": true
    },
    "loadout": [
        {
            "variation_id": 1271,
            "instance_id": 170658,
            "mounted_at": "2015-07-24T12:58:08+0000",
            "asset": {...}
        }
    ]
}

Get Current Loadout to Default Character

curl -X GET "https://api.lootlocker.io/game/v1/player/loadout" \
  -H "x-session-token: your_token_here"

Getting the current loadout will return an array of assets that the user currently have equipped.

A successful response will look similar to this

{
  "success": true,
  "loadout": [
    {
      "variation_id": 2,
      "instance_id": 538,
      "mounted_at": "2014-07-25T11:53:17+0000",
      "asset": {...}
    },
    {
      "variation_id": 9,
      "instance_id": 217,
      "mounted_at": "2014-07-25T11:53:17+0000",
      "asset": {...}
    }
  ]
}

The three fields returned in the call are:

Field name Description
item_id The id of the instance of the asset. This is the unique version of the asset that the player owns
mounted_at The date of equippal in ISO8601 format
asset The asset information needed to represent the asset in-game

Get Other Players Loadout to Default Character

curl -X GET "https://api.lootlocker.io/game/v1/player/loadout/76561198023004363?platform=steam" \
  -H "x-session-token: your_token_here"

This method will return the exact same response as the Get current loadout one, except that it will be for another player.

The platform parameter is optional. If you do not supply one, the backend is gonna default to the same one as the current player is on.

If the player does not exists, you will get a faulty response with the error field set to "Unknown player".

Get Equippable Contexts to Default Character

curl -X GET "https://api.lootlocker.io/game/v1/player/character/contexts" \
  -H "x-session-token: your_token_here"

This endpoint returns the contexts that the players default character can equip. The response format is the same as Getting Contexts, but only includes the equippable contexts for the character.

Get Equippable Contexts by Character ID

curl -X GET "https://api.lootlocker.io/game/v1/player/character/1234/contexts" \
  -H "x-session-token: your_token_here"

This endpoint returns the contexts that the requested player character can equip. The response format is the same as Getting Contexts, but only includes the equippable contexts for the character.

Character Progressions

Character progression API is used to track your character's progress on your game's progressions.

You can also add or subtract points, reset or delete character's progressions using this API.

Starting a character on a progression is as easy as just starting to add points to it.

Get Character Progressions

curl -X GET "https://api.lootlocker.io/game/player/characters/1/progressions?count=10&after=01GJN6J46DM00Z88WR225Y9P77"
-H "x-session-token: your_token_here"

Get list of progressions the character is currently on. Results are always sorted by ID.

URL Structure

/game/player/characters/<character_id>/progressions

Example Response

{
  "pagination": {
    "next_cursor": null,
    "previous_cursor": null,
    "total": 2
  },
  "items": [
  {
    "id": "01GJN6J46DM00Z88WR225Y9P77",
    "progression_key": "fighter",
    "progression_name": "Fighter",
    "step": 1,
    "points": 200,
    "previous_threshold": 0,
    "next_threshold": 500,
    "last_level_up": null
  },
  {
    "id": "01GJN6JGK3AV0N8YJ9GHSCJ4D3",
    "progression_key": "mage",
    "progression_name": "Mage",
    "step": 3,
    "points": 1300,
    "previous_threshold": 1000,
    "next_threshold": 2000,
    "last_level_up": "2022-11-24T16:12:41Z"
  }
  ]
}

URL Parts

Part Description
character_id ID of the character

Query Parameters:

Field Description
after Cursor for pagination, a cursor will be returned in the response
count Number of progressions returned per page. Max 500 is allowed

Get Character Progression By Key

curl -X GET "https://api.lootlocker.io/game/player/characters/1/progressions/fighter"
-H "x-session-token: your_token_here"

Get a single character progression by Key.

URL Structure

/game/player/characters/<character_id>/progressions/<progression_key>

Example Response

{
  "id": "01GJN6J46DM00Z88WR225Y9P77",
  "progression_key": "fighter",
  "progression_name": "Fighter",
  "step": 1,
  "points": 200,
  "previous_threshold": 0,
  "next_threshold": 500,
  "last_level_up": null
}

URL Parts

Part Description
progression_key Key of the progression
character_id ID of the character

Add points to a character progression

curl -X POST "https://api.lootlocker.io/game/player/characters/1/progressions/fighter/points/add" \
-H "x-session-token: your_token_here" \
-H "Content-Type: application/json" \
-d "{\"amount\": 1000 }"

Adds specified amount of points to a character progression. If the character is not on that progression it will be automatically started.

If the character leveled up, awarded_tiers fields will contain acquired rewards.

URL Structure

/game/player/characters/<character_id>/progressions/<progression_key>/points/add

Example Response

{
  "id": "01GJN6J46DM00Z88WR225Y9P77",
  "progression_key": "fighter",
  "progression_name": "Fighter",
  "step": 3,
  "points": 1200,
  "previous_threshold": 1000,
  "next_threshold": 2000,
  "last_level_up": "2022-11-24T16:12:41Z",
  "awarded_tiers": [
    {
      "step": 2,
      "points_threshold": 500,
      "rewards": {
        "progression_points_rewards": [
          {
            "progression_key": "blacksmithing",
            "progression_name": "Blacksmithing",
            "amount": 100
          }
        ],
        "progression_reset_rewards": [
          {
            "progression_key": "death_penalty_stacks",
            "progression_name": "Death penalty stacks"
          }
        ],
        "asset_rewards": [
          {
            "asset_id": 2,
            "asset_variation_id": null,
            "asset_rental_option_id": null
          }
        ],
        "currency_rewards": [
          {
            "currency_name": "Gold",
            "currency_code": "GLD",
            "amount": "100"
          }
        ]
      }
    },
    {
      "step": 3,
      "points_threshold": 1000,
      "rewards": {
        "progression_points_rewards": [],
        "progression_reset_rewards": [],
        "asset_rewards": [],
        "currency_rewards": []
      }
    }
  ]
}

URL Parts

Part Description
progression_key Key of the progression
character_id ID of the character

Available input fields

amount is required.

Field Description
amount Amount of points to be added to the character's progression.

Subtract points from a character progression

curl -X POST "https://api.lootlocker.io/game/player/characters/1/progressions/mage/points/subtract" \
-H "x-session-token: your_token_here" \
-d "{\"amount\": 10 }" \
-H "Content-Type: application/json"

Subtracts specified amount of points from a character progression. The character cannot go down a progression step, the points will be set to the previous_threshold if too many points are being subtracted.

URL Structure

/game/player/characters/<character_id>/progressions/<progression_key>/points/subtract

Example Response

{
    "id": "01GJN6JGK3AV0N8YJ9GHSCJ4D3",
    "progression_key": "mage",
    "progression_name": "Mage",
    "step": 3,
    "points": 1290,
    "previous_threshold": 1000,
    "next_threshold": 2000,
    "last_level_up": "2022-11-24T16:12:41Z",
    "awarded_tiers": []
}

URL Parts

Part Description
progression_key Key of the progression
character_id ID of the character

Available input fields

amount is required.

Field Description
amount Amount of points to be subtracted from the character's progression.

Reset a character progression

curl -X POST "https://api.lootlocker.io/game/player/characters/1/progressions/mage/reset" \
-H "x-session-token: your_token_here" \
-H "Content-Type: application/json"

Resets a character progression. This endpoint sets the character progression points to 0, so it still shows up as an active progression.

URL Structure

/game/player/characters/<character_id>/progressions/<progression_key>/reset

Example Response

{
    "id": "01GJN6JGK3AV0N8YJ9GHSCJ4D3",
    "progression_key": "mage",
    "progression_name": "Mage",
    "step": 1,
    "points": 0,
    "previous_threshold": 0,
    "next_threshold": 1000,
    "last_level_up": null,
    "awarded_tiers": []
}

URL Parts

Part Description
progression_key Key of the progression
character_id ID of the character

Delete a character progression

curl -X DELETE "https://api.lootlocker.io/game/player/characters/1/progressions/mage" \
-H "x-session-token: your_token_here" \
-H "Content-Type: application/json"

Deletes a character progression. It won't show up in character's active progression list.

URL Structure

/game/player/characters/<character_id>/progressions/<progression_key>

Example Response

This endpoint will not have a body, being a 204 No Content HTTP response.

URL Parts

Part Description
progression_key Key of the progression
character_id ID of the character

Heroes

In LootLocker, Heroes are an extension of Characters, which can have their own Default Loadouts, and have exceptions (either on an Asset or Context level) to what they can equip.

Get Game Heroes

curl -X GET "https://api.lootlocker.io/game/v1/heroes" \
  -H "x-session-token: your_token_here"

The first thing you will want to do is list the Heroes configured for your game, to get the information needed to create your Hero. This endpoint will list the Heroes with names and character information.

Example Response

{
    "success": true,
    "heroes": [
        {
            "hero_id": 2,
            "character_type_id": 1234,
            "character_type_name": "Heavy",
            "name": "Rick Astley",
            "player_has_hero": false,
            "asset": {...}
        }
    ]
}

List Player Heroes

curl -X GET "https://api.lootlocker.io/game/v1/player/heroes" \
  -H "x-session-token: your_token_here"

This endpoint will return any Heroes the player owns.

The id on the Hero property is the id of the instance of the Hero that the player owns, while the hero_id references the id of the Hero in your game. See how Get Game Heroes does not have an id property, but only a hero_id.

Example Response

{
    "success": true,
    "heroes": [
        {
            "id": 1,
            "hero_id": 2,
            "instance_id": 3,
            "hero_name": "Rick Astley",
            "character_name": "My First Hero",
            "class_name": "Heavy",
            "is_default": true,
            "asset_variation_id": 4,
            "asset": {...}
        }
    ]
}

The character_name property is the name that can be given to a Hero (and the underlying Character) by a player. You can safely ignore this if you do not want to use it.

The instance_id references an instance of the asset, that can be used like any other asset instance in LootLocker, for example, to store specific abilities or play time for a specific hero.

The asset_variation_id references the variation of the underlying asset backing the definition of this Hero. This can be used to create unique Heroes that share most properties, but differentiate in some parameters.

List Other Players Heroes by SteamID64

curl -X GET "https://api.lootlocker.io/game/v1/heroes/list/76000000000000000" \
  -H "x-session-token: your_token_here"

This endpoint will return any Heroes the player with the related SteamID64 owns.

The response form this endpoint is identical to listing heroes for the current players own Heroes. See List Player Heroes.

Example Response

{
    "success": true,
    "heroes": [
        {
            "id": 1,
            "hero_id": 2,
            "hero_name": "Rick Astley",
            "character_name": "My First Hero",
            "class_name": "Heavy",
            "is_default": true,
            "asset_variation_id": 4,
            "asset": {...}
        }
    ]
}

Creating a Hero

curl -X POST "https://api.lootlocker.io/game/v1/player/heroes" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d "{\"hero_id\": 2, \"name\": \"My First Hero\"}"

When creating a player owned hero, you need to supply the id of the game's hero, and can optionally supply a player set name. In the example we've named a "Rick Astley" Hero "My First Hero".

When creating a Hero, you can additionally add an optional asset_variation_id property to the request body. This will create a Hero with that specific variation from the asset. These heroes will also be treated as unique from other heroes with the same hero_id but a different asset_variation_id.

Example Response

{
    "success": true,
    "hero": {
        "id": 1,
        "hero_id": 2,
        "instance_id": 3,
        "hero_name": "Rick Astley",
        "character_name": "My First Hero",
        "class_name": "Heavy",
        "is_default": true,
        "asset_variation_id": 4,
        "asset": {...}
    }
}

Getting a Hero

curl -X GET "https://api.lootlocker.io/game/v1/player/heroes/1" \
  -H "x-session-token: your_token_here"

Calling this endpoint will return the information about a players hero.

Example Response

{
    "success": true,
    "hero": {
        "id": 1,
        "hero_id": 2,
        "instance_id": 3,
        "hero_name": "Rick Astley",
        "character_name": "My First Hero",
        "class_name": "Heavy",
        "is_default": true,
        "asset_variation_id": 4,
        "asset": {...}
    }
}

Get Other Players Default Hero By SteamID64

curl -X GET "https://api.lootlocker.io/game/v1/heroes/default/76000000000000000" \
  -H "x-session-token: your_token_here"

Use this endpoint to obtain the default hero for another player. This can be used when presenting heroes in a lobby before starting a game session etc.

The response is identical to the one of the Getting a Hero endpoint.

Example Response

{
    "success": true,
    "hero": {
        "id": 1,
        "hero_id": 2,
        "hero_name": "Rick Astley",
        "character_name": "My First Hero",
        "class_name": "Heavy",
        "is_default": true,
        "asset_variation_id": 4,
        "asset": {...}
    }
}

Updating a Hero

curl -X PUT "https://api.lootlocker.io/game/v1/player/heroes/1" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"Renamed Hero\", \"is_default\": false}"

Updating a hero allows you to change the player supplied name of the hero, and setting the default hero for the current player. Setting the default hero to true for one hero will automatically remove it from any other default hero the player might have.

Example Response

{
    "success": true,
    "hero": {
        "id": 1,
        "hero_id": 2,
        "instance_id": 3,
        "hero_name": "Rick Astley",
        "character_name": "Renamed Hero",
        "class_name": "Heavy",
        "is_default": false,
        "asset_variation_id": 4,
        "asset": {...}
    }
}

Deleting a Hero

curl -X DELETE "https://api.lootlocker.io/game/v1/player/heroes/1" \
  -H "x-session-token: your_token_here"

Deleting a hero will remove it from the players list of heroes. This action is currently unreversible, so you should make sure the player meant to perform the action.

When deleting a hero, the heroes inventory is returned to the player, and their loadout is reset.

Example Response

{ "success": true }

Get Hero Inventory

curl -X GET "https://api.lootlocker.io/game/v1/player/heroes/1/inventory" \
  -H "x-session-token: your_token_here"

This endpoint allows you to list asset instances owned by a hero. This is very similar to the player inventory, except that it just returns what is in a heroes inventory.

Note that this endpoint is paginated, and defaults to returning 50 entries. Using the count URL parameter you can set that up to 200.

To retrieve the next page, supply the after URL parameter, with the value of the highest instance_id from your last call.

Example Response

{
    "success": true,
    "inventory": [
        {
            "instance_id": 1,
            "variation_id": 1,
            "rental_option_id": null,
            "acquisition_source": "grant_default_loadout",
            "asset": {...},
            "rental": {
                "is_rental": false,
                "time_left": null,
                "duration": null,
                "is_active": null
            }
        }
    ]
}

Get Hero Loadout

curl -X GET "https://api.lootlocker.io/game/v1/player/heroes/1/loadout" \
  -H "x-session-token: your_token_here"

To list a heroes loadout, that is what is currently equipped in the hero, call this endpoint. This same data can also be obtained by getting the character whose inventory it inherits from using the Character Loadouts endpoint.

Example Response

{
    "success": true,
    "loadout": [
        {
            "variation_id": 2,
            "instance_id": 538,
            "mounted_at": "2014-07-25T11:53:17+0000",
            "asset": {...},
            "rental": {
                "is_rental": false,
                "time_left": null,
                "duration": null,
                "is_active": null
            }
        }
    ]
}

Get Other Players Hero Loadout

curl -X GET "https://api.lootlocker.io/game/v1/heroes/1/loadout" \
  -H "x-session-token: your_token_here"

When listing another player owned heroes loadout, you will need to supply the Hero ID in the URL, in this example 1. This ID can be obtained using the Get Other Players Default Hero By SteamID64 endpoint.

Example Response

{
    "success": true,
    "loadout": [
        {
            "variation_id": 2,
            "instance_id": 538,
            "mounted_at": "2014-07-25T11:53:17+0000",
            "asset": {...},
            "rental": {
                "is_rental": false,
                "time_left": null,
                "duration": null,
                "is_active": null
            }
        }
    ]
}

Add Asset to Hero Loadout

curl -X POST "https://api.lootlocker.io/game/v1/player/heroes/1/loadout" \
  TODO: Add data here
  -H "x-session-token: your_token_here"

To equip an asset instance, or a global asset, to a heroes loadout, you can call this endpoint. This endpoint works exactly like the Characters Equip endpoints, but lets you do the same operations on a hero directly instead of having to look up the character.

Example Response

{
    "success": true,
    "loadout": [
        {
            "variation_id": 2,
            "instance_id": 538,
            "mounted_at": "2014-07-25T11:53:17+0000",
            "asset": {...},
            "rental": {
                "is_rental": false,
                "time_left": null,
                "duration": null,
                "is_active": null
            }
        }
    ]
}

Remove Asset From Hero Loadout

curl -X DELETE "https://api.lootlocker.io/game/v1/player/heroes/3/loadout/537" \
  -H "x-session-token: your_token_here"

To unequip or remove an asset instance, or a global asset, from a heroes loadout, you can call this endpoint. This endpoint works exactly like the Characters Unequip endpoints, but lets you do the same operations on a hero directly instead of having to look up the character.

In the example request, we unequip an asset with the instance_id of 537.

If you have automatic removal of global assets enabled, there will be an extra property on the root of the response, called removed_asset (boolean), letting you know if the asset was removed from the player or not.

Example Response

{
    "success": true,
    "loadout": [
        {
            "variation_id": 2,
            "instance_id": 538,
            "mounted_at": "2014-07-25T11:53:17+0000",
            "asset": {...},
            "rental": {
                "is_rental": false,
                "time_left": null,
                "duration": null,
                "is_active": null
            }
        }
    ]
}

Leaderboards

In the context of the game API leaderboards can be used to view and submit scores for members. To read more about leaderboards in general you can read our Leaderboard Product Documentation.

An entry on a leaderboard is called a member. Since it's possible to have leaderboards for all kinds of cases it doesn't make sense to use players here. Because of that member_id can be whatever you want as long as it makes sense in your game. For lots of cases using the players ID will make good sense, but you can imagine a case where you would rank different clans/guilds against each other for example. In that case you would use clan/guild ID as member_id.

When using a leaderboard ID in any url it's possible to replace this with the key set on the leaderboard instead.

Leaderboard Types

Generic leaderboards

Use this if you want do not want the extended player details from the player type leaderboard. This type allows you to create leaderboards not meant for players (guild/clan for example), or if your player data is not stored in LootLocker.

Player leaderboards

Meant for LootLocker players leaderboards. When submitting scores, you can omit the member_id as the currently authenticated player will always be used by default. When retrieving data LootLocker will automatically attach player data such as name.

Metadata

Sometimes you want to store more data alongside the score for each entry on the leaderboard.

To accomplish this you can enable metadata on the leaderboard at the time of creation.

When submitting scores to that leaderboard you can send the metadata property with a string value in the request and that value will be automatically returned for that score entry.

Get Member Rank

Get rank for single member for a leaderboard.

If leaderboard is of type player a player will also be in the response.

If metadata is enabled for the leaderboard, that will be returned in the response.

curl -X GET "https://api.lootlocker.io/game/leaderboards/1/member/1" \
  -H "x-session-token: your_token_here"

Example Response

{
  "member_id": "1",
  "rank": 3,
  "score": 3004,
  "player": {
    "id": 1,
    "public_uid": "TSEYDXD8",
    "name": "Player Name"
  },
  "metadata": "some metadata"
}

URL Structure

/game/leaderboards/<leaderboard_id|leaderboard_key>/member/<member_id>

URL Parts

Part Description
leaderboard_id ID of the leaderboard
leaderboard_key key of the leaderboard
member_id player_id if player type leaderboard, otherwise id used when submitting the score

Get By List of Members

Get ranks for list of members for a leaderboard. This can be helpful when getting a players friends on leaderboard.

If leaderboard is of type player a player will also be in the response.

If metadata is enabled for the leaderboard, that will be returned in the response.

curl -X POST "https://api.lootlocker.io/game/leaderboards/1/members" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d "{\"members\": [\"1\", \"2\"]}"

Example Response

{
  "members": [
    {
      "member_id": "1",
      "rank": 1,
      "score": 10000,
      "player": {
        "id": 1,
        "public_uid": "TSEYDXD8",
        "name": "Player Name"
      },
      "metadata": "some metadata"
    },
    {
      "member_id": "2",
      "rank": 10,
      "score": 5000,
      "player": {...},
      "metadata": "some other metadata"
    }
  ]
}

Get All Member Ranks

curl -X GET "https://api.lootlocker.io/game/leaderboards/member/4?count=1" \
  -H "x-session-token: your_token_here"

Get all leaderboards with member information on the ones the member is on, with rank and score, as well as player information if the leaderboard is of type player.

If metadata is enabled for the leaderboard, that will be returned in the response.

Example Response

{
  "leaderboards": [
    {
      "rank": {
        "rank": 1,
        "member_id": "4",
        "score": 134076416,
        "player": {
          "name": "Player Name",
          "id": 4,
          "public_uid": "ABCD1234",
          "metadata": "some metadata"
        }
      },
      "leaderboard_id": 1,
      "leaderboard_key": "LeaderboardKey"
    }
  ],
  "pagination": {
    "total": 100,
    "next_cursor": "2",
    "previous_cursor": null
  }
}

URL Structure

/game/leaderboards/member/<member_id>?count=1&after=0

URL Parts

Part Description
game_id ID of the game
member_id player_id if player type leaderboard, otherwise id used when submitting the score

Query Parameters

Field Description
after Cursor for pagination, a cursor will be returned in the response
count Number of members returned per page

Get Score List

curl -X GET "https://api.lootlocker.io/game/leaderboards/1/list?count=10" \
  -H "x-session-token: your_token_here"

Get list of members in rank range. Result is sorted by rank ascending. Maximum allowed members to query for at a time is currently 2000.

If leaderboard is of type player a player will also be in the response.

If metadata is enabled for the leaderboard, that will be returned in the response.

Example Response

{
  "pagination": {
    "total": 10132,
    "next_cursor": 3,
    "previous_cursor": null
  },
  "items": [
    {
      "member_id": "test_id",
      "rank": 1,
      "score": 10000,
      "player": {
        "id": 123,
        "public_uid": "TSEYDXD8",
        "name": "Player Name"
      },
      "metadata": "some metadata"
    },
    {
      "member_id": "test_id2",
      "rank": 2,
      "score": 9999,
      "player": {...},
      "metadata": "some other metadata"
    },
    {
      "member_id": "test_id3",
      "rank": 3,
      "score": 7500,
      "player": {...},
      "metadata": "some third type of metadata"
    }
  ]
}

URL Structure

/game/leaderboards/<leaderboard_id|leaderboard_key>/list?count=10&after=0

URL Parts

Part Description
leaderboard_id ID of the leaderboard
leaderboard_key key of the leaderboard

Query Parameters

Field Description
after Cursor for pagination, a cursor will be returned in the response
count Number of members returned per page

Submit Score

curl -X POST "https://api.lootlocker.io/game/leaderboards/1/submit" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d "{\"score\": 1000, \"metadata\": \"some metadata\"}"

Example Response

{
  "member_id": "2",
  "rank": 4,
  "score": 1000,
  "metadata": "some metadata"
}

URL Structure

/game/leaderboards/<leaderboard_id|leaderboard_key>/submit

URL Parts

Part Description
leaderboard_id ID of the leaderboard
leaderboard_key key of the leaderboard

Available input fields

All fields are optional.

Field Description
member_id optional player_id if player type leaderboard, otherwise id used when submitting the score
score The score for the entry
metadata If enabled on the leaderboard you can send this. Only accepts a string

Submit scores for member on leaderboard. The member_id in the Game API is automatically filled with the currently authenticated players id.

If metadata is enabled for the leaderboard, that will be returned in the response.

Progressions

Progressions API allows you to fetch all progressions for your game.

Progressions can be used to track player progress, ranging from player levels, class levels, achievements, battle passes and everything in between.

Your game can have as many progressions as you need and your players can progress through as many as your game requires them to, possibilities are endless.

Get All Progressions

curl -X GET "https://api.lootlocker.io/game/progressions?count=10&after=01GJ34JX0VKJKM4P6X9JHZ8FDF"
-H "x-session-token: your_token_here"

Get a list of all progressions. Results are always sorted by ID.

URL Structure

/game/progressions

Example Response

{
  "pagination": {
    "total": 3,
    "next_cursor": null,
    "previous_cursor": null
  },
  "items": [
    {
      "id": "01GJ34JX0VKJKM4P6X9JHZ8FDF",
      "key": "fighter",
      "name": "Fighter",
      "active": true,
    },
    {
      "id": "01GJ34969HM62X7DWTQ0QWEXVP",
      "key": "mage",
      "name": "Mage",
      "active": true,
    },
    {
      "id": "01GS5V8TGKA1DFFYH16JDYA4PC",
      "key": "blacksmithing",
      "name": "Blacksmithing",
      "active": true
    },
    {
      "id": "01GJ34K7QBEB124MVE8BCFPAMG",
      "key": "death_penalty_stacks",
      "name": "Death penalty stacks",
      "active": true
    }
  ]
}

Query Parameters:

Field Description
after Cursor for pagination, a cursor will be returned in the response
count Number of progressions returned per page. Max 500 is allowed

Get Progression By Key

curl -X GET "https://api.lootlocker.io/game/progressions/fighter"
-H "x-session-token: your_token_here"

Get a single progression by key.

URL Structure

/game/progressions/<progression_key>

Example Response

{
  "id": "01GJ34JX0VKJKM4P6X9JHZ8FDF",
  "key": "fighter",
  "name": "fighter",
  "active": true,
}

URL Parts

Part Description
progression_key Key of the progression

Get Single Progression Tier

curl -X GET "https://api.lootlocker.io/game/progressions/fighter/tiers/2"
-H "x-session-token: your_token_here"

Gets a single progression tier with rewards.

URL Structure

/game/<game_id>/progressions/<progression_key>/tiers/<progression_step>

Example Response

{
  "step": 2,
  "points_threshold": 500,
  "rewards": {
    "progression_points_rewards": [
      {
        "progression_key": "blacksmithing",
        "progression_name": "Blacksmithing",
        "amount": 100
      }
    ],
    "progression_reset_rewards": [
      {
        "progression_key": "death_penalty_stacks",
        "progression_name": "Death penalty stacks"
      }
    ],
    "asset_rewards": [
      {
        "asset_id": 2,
        "asset_variation_id": null,
        "asset_rental_option_id": null
      }
    ],
    "currency_rewards": [
      {
        "currency_name": "Gold",
        "currency_code": "GLD",
        "amount": "100"
      }
    ]
  }
}

URL Parts

Part Description
progression_key Key of the progression
progression_step Key of the progression

Get All Progressions Tiers

curl -X GET "https://api.lootlocker.io/game/progressions/fighter/tiers?count=10&after=1"
-H "x-session-token: your_token_here"

Get list of tiers for the progression and their rewards. Results are always sorted by progression tier step in ascending order.

Note that for pagination the step is used as the cursor instead of the ID.

URL Structure

/game/<game_id>/progressions/<progression_key>/tiers

Example Response

{
  "pagination": {
    "next_cursor": null,
    "previous_cursor": null,
    "total": 5
  },
  "items": [
    {
      "step": 1,
      "points_threshold": 0,
      "rewards": {
        "progression_points_rewards": [],
        "progression_reset_rewards": [],
        "asset_rewards": []
      }
    },
    {
      "step": 2,
      "points_threshold": 500,
      "rewards": {
        "progression_points_rewards": [
          {
            "progression_key": "blacksmithing",
            "progression_name": "Blacksmithing",
            "amount": 100
          }
        ],
        "progression_reset_rewards": [
          {
            "progression_key": "death_penalty_stacks",
            "progression_name": "Death penalty stacks"
          }
        ],
        "asset_rewards": [
          {
            "asset_id": 2,
            "asset_variation_id": null,
            "asset_rental_option_id": null
          }
        ],
        "currency_rewards": [
          {
            "currency_name": "Gold",
            "currency_code": "GLD",
            "amount": "100"
          }
        ]
      }
    },
    {
      "step": 3,
      "points_threshold": 1000,
      "rewards": {
        "progression_points_rewards": [],
        "progression_reset_rewards": [],
        "asset_rewards": [
          {
            "asset_id": 3,
            "asset_variation_id": null,
            "asset_rental_option_id": null
          }
        ],
        "currency_rewards": []
      }
    },
    {
      "step": 4,
      "points_threshold": 5000,
      "rewards": {
        "progression_points_rewards": [
          {
            "progression_key": "blacksmithing",
            "progression_name": "Blacksmithing",
            "amount": 100
          }
        ],
        "progression_reset_rewards": [],
        "asset_rewards": [],
        "currency_rewards": []
      }
    },
    {
      "step": 5,
      "points_threshold": 10000,
      "rewards": {
        "progression_points_rewards": [],
        "progression_reset_rewards": [],
        "asset_rewards": [],
        "currency_rewards": []
      }
    }
  ]
}

URL Parts

Part Description
progression_key Key of the progression

Query Parameters:

Field Description
after Cursor for pagination, a cursor will be returned in the response
count Number of progressions returned per page. Max 500 is allowed

Persistent Player Storage

Get Entire Persistent Storage

curl -X GET "https://api.lootlocker.io/game/v1/player/storage" \
  -H "x-session-token: your_token_here"

The persistent storage lets you save key/value pairs for each player for, syncing settings on different computers or other needs.

This call returns all key/value pairs on record for this player, and can thus be slow if you create many.

Sample success response

{
  "success": true,
  "payload": [
    {
      "key": "user.answer",
      "value": "42",
      "is_public": false
    }
  ]
}

Get Multiple Players Public Persistent Storage Values

curl -X POST "https://api.lootlocker.io/game/player/storage/lookup" \
  -H "Content-Type: application/json" \
  -d '
{
  "keys": [
    "key_1",
    "key_2"
  ],
  "player_ids": [
    1,
    2
  ]
}'

This endpoints returns public storage values for multiple players and keys.

If the keys array is empty in the request it will return all keys from the player storage, otherwise it will return only the keys specified in the array. player_ids array is required, it needs to contain at least 1 value.

Sample success response

{
  "storages": [
    {
      "player_id": 1,
      "storage": [
        {
          "key": "key_1",
          "value": "value_1",
          "is_public": true
        },
        {
          "key": "key_2",
          "value": "value_2",
          "is_public": true
        }
      ]
    },
    {
      "player_id": 2,
      "storage": [
        {
          "key": "key_1",
          "value": "value_1",
          "is_public": true
        },
        {
          "key": "key_2",
          "value": "value_2",
          "is_public": true
        }
      ]
    }
  ]
}

Get a Single Key From Persistent Storage

curl -X GET "https://api.lootlocker.io/game/v1/player/storage?key=user.something" \
  -H "x-session-token: your_token_here"

Very much like the above, except this call only returns one key/value set.

Sample success response

{
  "success": true,
  "payload": {
    "key": "user.answer",
    "value": "42",
    "is_public": false
  }
}

Updating / Creating Key/Value Pairs

curl -X POST "https://api.lootlocker.io/game/v1/player/storage" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d '
[
  {
    "key": "totalDeaths",
    "value": "124",
    "is_public": true,
    "order": 1
  },
  {
    "key": "animal",
    "value": "Sheep",
    "order": 2
  }
]'

The response from this request will be that of Get Entire Persistent Storage.

For the key, the following rules apply:

Rule Restriction
Max length 60 characters

For the value, the following rules apply:

Rule Restriction
Max length 1500 characters

Note that you can mark a key/value pair as public by including a boolean in the object, named is_public set to true. If you do not want the key/value pair to be public, either send it with the value set to false or omit the key.

For the order you must supply an incrementing integer for each pair. This integer does not have to be continuously increasing, 12, 34, 71 is a perfectly valid sequence.

Deleting a Key/Value Pair

curl -X DELETE "https://api.lootlocker.io/game/v1/player/storage?key=fruit" \
  -H "x-session-token: your_token_here"

When successfully deleting a key/value pair, you will get a response that equals that from Get Entire Persistent Storage. If an error occurs, you will get a 500 Internal Error response, and you should simply try again (for a limited number of times).

Getting Other Players Public Key/Value Pairs

When you need to read another players public key/value storage, you can either use the players id or their public UID.

The response will have the same format as any other player storage API call.

Get by Player ID

curl -X GET "https://api.lootlocker.io/game/v1/player/1234/storage" \
  -H "x-session-token: your_token_here"

Get by Player Public UID

curl -X GET "https://api.lootlocker.io/game/v1/player/A1B2C3D4/storage" \
  -H "x-session-token: your_token_here"

Sample success response

{
  "success": true,
  "payload": [
    {
      "key": "user.answer",
      "value": "42",
      "is_public": true
    }
  ]
}

Asset

Getting Contexts

curl -X GET "https://api.lootlocker.io/game/v1/contexts" \
  -H "x-session-token: your_token_here"

This endpoint will return all the contexts the game has. This includes if a context is locked by an asset or not, for easy handling game side.

Example Response

{
  "success": true,
  "contexts": [
    {
      "id": 3,
      "uuid": "79838f0f-cc37-4854-a81f-eedf7be469b8",
      "name": "Credits",
      "friendly_name": null,
      "detachable": false,
      "user_facing": false,
      "dependent_asset_id": null
    },
    {
      "id": 4,
      "uuid": "4785e978-09f9-4e07-83bd-ed36600930d4",
      "name": "Arms",
      "friendly_name": "Hands",
      "detachable": false,
      "user_facing": true,
      "dependent_asset_id": null
    },
    {
      "id": 5,
      "uuid": "8b860287-5d50-4948-8661-75dbe87b6506",
      "name": "Bindings",
      "friendly_name": null,
      "detachable": false,
      "user_facing": true,
      "dependent_asset_id": null
    },
    {
      "id": 6,
      "uuid": "20914798-d428-4a11-99a1-64ebac1c8d60",
      "name": "Goggles",
      "friendly_name": "Eyes",
      "detachable": true,
      "user_facing": true,
      "dependent_asset_id": null
    }
  ]
}

Getting Asset List

First call

curl -X GET "https://api.lootlocker.io/game/v1/assets/list?count=10&filter=purchasable" \
  -H "x-session-token: your_token_here"

This call is a non-streamed version of the Getting All Assets. It will require multiple calls to LootLocker with a parameter for every call except the first to step forward in the results.

Up to 200 (the default limit is 50 though) assets are returned at a time, and to fetch the next page you have to use the largest ID you've gotten returned in the previous response, in the parameter ?after in the URL. Once you get no assets returned you have gotten them all.

You can set a custom limit, up to 200 items that will be returned, using the query variable count=200. If a non-numeric value is supplied or it's bigger than 200, it will be ignored and a default limit of 50 will be applied.

Next call

curl -X GET "https://api.lootlocker.io/game/v1/assets/list?after=1927&count=10&filter=purchasable" \
  -H "x-session-token: your_token_here"

This endpoint also supports filtering assets, using a ?filter URL parameter. Currently the following filters exist:

Filter value Effect
purchasable Only return purchasable assets
!purchasable Only return non-purchasable assets
rentable Only return rentable assets
!rentable Only return non-rentable assets
popular Only return popular assets
!popular Only return non-popular assets

Filters can also be combined by separating them with a comma. To only get purchasable and popular assets, use the following: purchasable,popular.

If you want to only get assets from a specific context, you can pass along a context_id property with the ID of the context you want to get assets from. Eg. ?after=1927&context_id=192

The objects returned in the array, are the same as returned and documented in the Getting All Assets call. Please reference the text there for detailed information about the properties.

Example Response

{
  "success": true,
  "assets": [
    {
      "id": 1928,
      "uuid": "b85292be-f244-440d-b7ec-d3fbb3775edb",
      "name": "Jester Pro",
      "active": true,
      "purchasable": false,
      "price": 259,
      "sales_price": null,
      "display_price": "259",
      "context": "Bindings",
      "context_id": 2,
      "character_classes": [1, 2, 3],
      "unlocks_context": null,
      "detachable": false,
      "updated": "Sun, 07 Jan 2018 08:35:34 +0000",
      "marked_new": null,
      "default_variation_id": 2579,
      "default_loadouts": {
        "skier": false,
        "snowboarder": false
      },
      "description": "",
      "links": {
        "thumbnail": "CharacterAttachments/Item Thumbnails/bindings/marker/thumb_marker-14-jesterpro.tif"
      },
      "storage": [
        {
          "key": "a key",
          "value": "the value"
        }
      ],
      "rarity": {
        "name": "Legend",
        "short_name": "",
        "color": "BA8BFD"
      },
      "popular": false,
      "popularity_score": 0,
      "package_contents": null,
      "unique_instance": false,
      "external_identifiers": null,
      "rental_options": null,
      "filters": [
        {
          "value": "Marker",
          "name": "Brand"
        },
        {
          "value": "14/15",
          "name": "Season"
        }
      ],
      "variations": [
        {
          "id": 2579,
          "name": "marker-14-jesterpro",
          "primary_color": "98372B",
          "secondary_color": "AE2C1C",
          "links": {
            "thumbnail": "CharacterAttachments/Item Thumbnails/bindings/marker/thumb_marker-14-jesterpro.tif"
          },
          "properties": [
            {
              "material_path": "CharacterAttachments/Bindings/Marker/marker-14-jesterpro/marker-14-jesterpro.mtl",
              "binding_path": "CharacterAttachments/bindings/marker/marker-13-jester18pro/marker-13-jester18pro.cgf",
              "bone_id": 75,
              "bone_overrides": {}
            },
            {
              "material_path": "CharacterAttachments/Bindings/Marker/marker-14-jesterpro/marker-14-jesterpro.mtl",
              "binding_path": "CharacterAttachments/bindings/marker/marker-13-jester18pro/marker-13-jester18pro.cgf",
              "bone_id": 74,
              "bone_overrides": {}
            }
          ]
        }
      ],
      "featured": false,
      "context_locked": false,
      "initially_purchasable": false,
      "files": [
        {
          "url": "https://cdn.lootlocker.io/141/5f230b1e14614.txt",
          "tags": ["never", "gonna", "give", "you", "up"]
        }
      ],
      "data_entities": ["Your games custom", "data for this asset"],
      "asset_candidate": {
        "created_by_player_id": 1234,
        "created_by_player_uid": "A1B2C3D4"
      },
      "drop_table_max_picks": null
    }
  ]
}

If your game has UGC enabled, you can send a GET style url parameter along to have UGC Assets returned: ?include_ugc=true. You can also filter for just one specific creator by sending a player id in the parameter ugc_creator_player_id. This parameter can only be sent when the include_ugc parameter is also sent and set to true.

If you only want a subset of the assets your game owns, you can use the filters to include only the ones you want, by adding a GET style parameter to the url like so: ?asset_filters=key1=value1;key2=value2 etc. Any filters supplied need to be present on all assets for them to be returned. A maximum of 5 filters can be applied, any additional filters will be ignored.

You can also do a free text search in the assets name by using the query parameter search. This will return all assets that match the search string in their name.

Getting Assets By IDs

curl -X GET "https://api.lootlocker.io/game/v1/assets/by/id?asset_ids=1,2,3,4" \
  -H "x-session-token: your_token_here"

This endpoint lets you retrieve only specific Assets by their ID's. The response is identical to the one from Getting Asset List.

Alternatively Get Assets By UUIDs

curl -X GET "https://api.lootlocker.io/game/v1/assets/by/id?asset_ids=e76310bb-3cac-4017-b7c8-f010a317058e,55d18841-e07d-4453-ba6a-20677902f74a" \
  -H "x-session-token: your_token_here"

You can also use the Asset's UUID with this endpoint, if you need an identifier that does not change between the live and development version of your games.

Getting All Assets

Get all

curl -X GET "https://api.lootlocker.io/game/v1/assets" \
  -H "x-session-token: your_token_here"

This call is a little special as it will stream you multiple JSON objects, which you will need to be able to handle on your end.

The first JSON object you will receive is a success status.

Get since a date

curl -X GET "https://api.lootlocker.io/game/v1/assets?since=2014-10-15 19:11:53" \
  -H "x-session-token: your_token_here"

After that object you will start receiving the asset objects. See example object to the right. These objects will be valid JSON in their own entities, and they will arrive one at a time. You should parse and handle them as they come in.

The end of the request is marked by JSON object with just one key; streamedObjectCount. This will hold an integer of how many assets were sent. Once this is received you can safely close the connection.

Example of the first object you will receive

{ "success": true }

The price and sales_price fields is for displaying a price in the store. If the asset is currently discounted, the sales_price will be set to a non-null value, and you should display that instead of the price field. You can use the difference between the two prices to calculate percentage or discount amount if you wish to do so. display_price is a formatted value sent by the backend, as a string. For virtual currencies it will hold just a number, but for real world currencies it will show the correct price in local currency (Only Play Station currently. Steam will just show the USD price set on the backend). This is useful when listing credits for sale, or if your game does not use virtual currencies.

The type field references types you can arbitrarily set in the management interface. These are to help you differentiate between what different kinds of assets you might have, such as "clothing", "currency", "equipment" etc.

The featured field lets you know if this asset is featured or not. Do with that information what you want. If the asset is an asset for sale, take the player to the store. If it's an event that everyone can participate in, take them to it etc.

The marked_new field lets you annotate your assets with a new badge or similar. This date is in the format RFC-2822, but it can also contain a null value in case it's never been set.

The detachable field lets you know if this is an asset that can be detached, such that the player can choose to not use it in their loadout. If an asset if is a type that does not have a context, the detachable flag will be null.

The context_locked field lets you know if this asset is currently locked because the player does not own the necessary asset to grant access to it's context.

The unlocks_context field is a string with the name of the context that it unlocks. If the asset does not unlock any context, the value will be null.

To handle rental, have a look at rental_options, which specifies the price for rental tiers, a name for each of them and so forth. The duration field is the duration of the rental in seconds.

Under each binding you will see a bone_id, which refers to bones returned from the asset bone call. If there are any deviations from a standard bone, it will be sent along with the binding information. See the example.

You will also see filters if any are defined in the backend. In this example there is one called Brand and one called Season. Do with these what you please.

Under the storage property you will see the keys and values set in the LootLocker Management Console.

The character_classes property contains a list of the ID's of the character classes that can equip this asset.

Example of the asset objects you will receive

{
  "id": 4,
  "uuid": "197261a8-b5be-47ef-874c-830c554595a1",
  "name": "Sven",
  "active": true,
  "price": 0,
  "sales_price": null,
  "display_price": "0",
  "shop_thumbnail": "CharacterAttachments/Item Thumbnails/hands/lo2/thumb_lo2-gloves-13-sven.tif",
  "context": "Arms",
  "context_id": 1,
  "character_classes": [1, 2, 3],
  "detachable": true,
  "purchasable": true,
  "initially_purchasable": true,
  "updated": "Wed, 04 Feb 2015 15:17:00 +0000",
  "marked_new": "Tue, 20 Oct 2015 21:53:45 +0000",
  "default_variation_id": 3,
  "default_loadouts": {
    "skier": true,
    "snowboarder": false
  },
  "description": "Asset description",
  "featured": false,
  "context_locked": false,
  "unlocks_context": null,
  "rarity": {
    "name": "Legendary",
    "short_name": "L",
    "color": "336699"
  },
  "popular": true,
  "popularity_score": 11618,
  "unique_instance": false,
  "external_identifiers": {
    "psn": {
      "entitlement_id": "CRED01",
      "service_label": 1
    },
    "apple_app_store": {
      "product_id": "CRED01"
    },
    "google_play": {
      "product_id": "CRED01"
    }
  },
  "variations": [
    {
      "id": 3,
      "name": "lo2-gloves-13-sven",
      "primary_color": "FFFFFF",
      "secondary_color": null,
      "properties": [
        {
          "material_path": "CharacterAttachments/hands/lo2/lo2-gloves-13-sven/lo2-gloves-13-sven.mtl",
          "binding_path": "CharacterAttachments/hands/shared-meshes/gloves-a/gloves-a.skin",
          "bone_id": 12,
          "bone_overrides": {}
        }
      ],
      "links": {
        "thumbnail": "CharacterAttachments/Item Thumbnails/hands/lo2/thumb_lo2-gloves-13-sven.tif"
      }
    },
    {
      "id": 4,
      "name": "lo2-gloves-13-sven_white",
      "primary_color": "FFFFFF",
      "secondary_color": null,
      "properties": [
        {
          "material_path": "CharacterAttachments/hands/lo2/lo2-gloves-13-sven/lo2-gloves-13-sven_white.mtl",
          "binding_path": "CharacterAttachments/hands/shared-meshes/gloves-a/gloves-a.skin",
          "bone_id": 12,
          "bone_overrides": {}
        }
      ],
      "links": {
        "thumbnail": "CharacterAttachments/Item Thumbnails/hands/lo2/thumb_lo2-gloves-13-sven.tif"
      }
    },
    {
      "id": 5,
      "name": "lo2-gloves-13-sven_green",
      "primary_color": "FFFFFF",
      "secondary_color": null,
      "properties": [
        {
          "material_path": "CharacterAttachments/hands/lo2/lo2-gloves-13-sven/lo2-gloves-13-sven_green.mtl",
          "binding_path": "CharacterAttachments/hands/shared-meshes/gloves-a/gloves-a.skin",
          "bone_id": 12,
          "bone_overrides": {}
        }
      ],
      "links": {
        "thumbnail": "CharacterAttachments/Item Thumbnails/hands/lo2/thumb_lo2-gloves-13-sven.tif"
      }
    }
  ],
  "filters": [
    {
      "value": "lo2",
      "name": "Brand"
    },
    {
      "value": "13/14",
      "name": "Season"
    }
  ],
  "rental_options": [
    {
      "id": 1,
      "name": "3 Day Ski Pass",
      "duration": 259200,
      "price": 49,
      "sales_price": null,
      "links": {
        "thumbnail": "CharacterAttachments/Item Thumbnails/hands/lo2/thumb_lo2-gloves-13-sven-rental-3-days.tif"
      }
    }
  ],
  "files": [
    {
      "url": "https://cdn.lootlocker.io/141/5f230b1e14614.txt",
      "tags": ["never", "gonna", "give", "you", "up"]
    }
  ],
  "data_entities": ["Your games custom data for this asset"],
  "asset_candidate": {
    "created_by_player_id": 1234,
    "created_by_player_uid": "A1B2C3D4"
  },
  "drop_table_max_picks": null
}

The end of the request is marked by a small object indicating how many assets were sent

{ "streamedObjectCount": 7 }

Example of the asset object with bone variations

{
    "id": 4,
    "uuid": "197261a8-b5be-47ef-874c-830c554595a1",
    "name": "Sven",
    "active": true,
    "price": 0,
    "sales_price": null,
    "display_price": "0",
    "shop_thumbnail": "CharacterAttachments\/Item Thumbnails\/hands\/lo2\/thumb_lo2-gloves-13-sven.tif",
    "context": "Arms",
    "context_id": 1,
    "character_classes": [1,2,3],
    "detachable": true,
    "updated": "Wed, 04 Feb 2015 15:17:00 +0000",
    "marked_new": "Tue, 20 Oct 2015 21:53:45 +0000",
    "default_variation_id": 3,
    "default_loadouts": {
        "skier": true,
        "snowboarder": false
    },
    "description": "",
    "featured": false,
    "rarity": {
      "name": "Legendary",
      "short_name": "L",
      "color": "336699"
    },
    "popular": true,
    "popularity_score": 11618,
    "unique_instance": false,
    "external_identifiers": {
        "psn": {
            "entitlement_id": "CRED01",
            "service_label": 1
        },
        "apple_app_store": {
            "product_id": "CRED01"
        },
        "google_play": {
            "product_id": "CRED01"
        }
    },
    "variations": [
        {
            "id": 3,
            "name": "lo2-gloves-13-sven",
            "primary_color": "FFFFFF",
            "secondary_color": null,
            "properties": [
                {
                    "material_path": "CharacterAttachments\/hands\/lo2\/lo2-gloves-13-sven\/lo2-gloves-13-sven.mtl",
                    "binding_path": "CharacterAttachments\/hands\/shared-meshes\/gloves-a\/gloves-a.skin",
                    "bone_id": 12,
                    "bone_overrides": [
                        {
                            "name": "Position",
                            "value": "0,0.24771199,0.8292712"
                        }
                    ]
                }
            ],
            "links": {
                "thumbnail": "CharacterAttachments\/Item Thumbnails\/hands\/lo2\/thumb_lo2-gloves-13-sven.tif"
            }
        },
        {
            "id": 4,
            "name": "lo2-gloves-13-sven_white",
            "primary_color": "FFFFFF",
            "secondary_color": null,
            "properties": [
                {
                    "material_path": "CharacterAttachments\/hands\/lo2\/lo2-gloves-13-sven\/lo2-gloves-13-sven_white.mtl",
                    "binding_path": "CharacterAttachments\/hands\/shared-meshes\/gloves-a\/gloves-a.skin",
                    "bone_id": 12,
                    "bone_overrides": [
                        {
                            "name": "Position",
                            "value": "0,0.24771199,0.8292712"
                        }
                    ]
                }
            ],
            "links": {
                "thumbnail": "CharacterAttachments\/Item Thumbnails\/hands\/lo2\/thumb_lo2-gloves-13-sven.tif"
            }
        },
        {
            "id": 5,
            "name": "lo2-gloves-13-sven_green",
            "primary_color": "FFFFFF",
            "secondary_color": null,
            "properties": [
                {
                    "material_path": "CharacterAttachments\/hands\/lo2\/lo2-gloves-13-sven\/lo2-gloves-13-sven_green.mtl",
                    "binding_path": "CharacterAttachments\/hands\/shared-meshes\/gloves-a\/gloves-a.skin",
                    "bone_id": 12,
                    "bone_overrides": {

                    }
                }
            ],
            "links": {
                "thumbnail": "CharacterAttachments\/Item Thumbnails\/hands\/lo2\/thumb_lo2-gloves-13-sven.tif"
            }
        }
    ],
    "filters": [
        {
            "value": "lo2",
            "name": "Brand",
        },
        {
            "value": "13\/14",
            "name": "Season",
        }
    ],
    "rental_options": [
        {
            "id": 1,
            "name": "3 Day Ski Pass",
            "duration": 259200,
            "price": 49,
            "sales_price": null,
            "links": {
                "thumbnail": "CharacterAttachments\/Item Thumbnails\/hands\/lo2\/thumb_lo2-gloves-13-sven-rental-3-days.tif"
            }
        }
    ],
    "storage": [
        {
            "key": "dog",
            "value": "yes"
        }
    ],
    "files": [
        {
            "url": "https://cdn.lootlocker.io/141/5f230b1e14614.txt",
            "tags": [
                "never",
                "gonna",
                "give",
                "you",
                "up"]
        }
    ],
    "data_entities": [
        "Your games custom data for this asset"
    ],
    "asset_candidate": {
        "created_by_player_id": 1234,
        "created_by_player_uid": "A1B2C3D4"
    },
    "drop_table_max_picks": null
}
{
    "id": 1,
    "name": "Sven",
    "active": true,
    "price": 0,
    "sales_price": null,
    "display_price": "0",
    "shop_thumbnail": "CharacterAttachments/Item Thumbnails/hands/lo2/thumb_lo2-gloves-13-sven.tif",
    "context": "Arms",
    "context_id": 1,
    "character_classes": [1,2,3],
    "detachable": true,
    "updated": "Tue, 13 Jan 2015 14:14:28 +0000",
    "marked_new": "Tue, 20 Oct 2015 21:53:45 +0000",
    "default_variation_id": 1,
    "default_loadouts": {
        "skier": true,
        "snowboarder": false
    },
    "description": "",
    "popularity_score": 11618,
    "unique_instance": false,
    "external_identifiers": {
        "psn": {
            "entitlement_id": "CRED01",
            "service_label": 1
        },
        "apple_app_store": {
            "product_id": "CRED01"
        },
        "google_play": {
            "product_id": "CRED01"
        }
    },
    "variations": [
        {
            "id": 1,
            "name": "lo2-gloves-13-sven",
            "primary_color": "FFFFFF",
            "secondary_color": null,
            "properties": [
                {
                    "material_path": "CharacterAttachments/hands/lo2/lo2-gloves-13-sven/lo2-gloves-13-sven.mtl",
                    "binding_path": "CharacterAttachments/hands/shared-meshes/gloves-a/gloves-a.skin",
                    "bone_id": 12,
                    "bone_overrides": [
                        {
                            "name": "Position",
                            "value": "0,0.24771199,0.8292712"
                        }
                    ]
                }
            ],
            "links": {
                "thumbnail": "CharacterAttachments\/Item Thumbnails\/hands\/lo2\/thumb_lo2-gloves-13-sven.tif"
            }
        },
        {
            "id": 2,
            "name": "lo2-gloves-13-sven_white",
            "primary_color": "FFFFFF",
            "secondary_color": null,
            "properties": [
                {
                    "material_path": "CharacterAttachments/hands/lo2/lo2-gloves-13-sven/lo2-gloves-13-sven_white.mtl",
                    "binding_path": "CharacterAttachments/hands/shared-meshes/gloves-a/gloves-a.skin",
                    "bone_id": 12,
                    "bone_overrides": [
                        {
                            "name": "Position",
                            "value": "0,0.24771199,0.8292712"
                        }
                    ]
                }
            ],
            "links": {
                "thumbnail": "CharacterAttachments\/Item Thumbnails\/hands\/lo2\/thumb_lo2-gloves-13-sven.tif"
            }
        },
        {
            "id": 3,
            "name": "lo2-gloves-13-sven_green",
            "primary_color": "FFFFFF",
            "secondary_color": null,
            "properties": [
                {
                    "material_path": "CharacterAttachments/hands/lo2/lo2-gloves-13-sven/lo2-gloves-13-sven_green.mtl",
                    "binding_path": "CharacterAttachments/hands/shared-meshes/gloves-a/gloves-a.skin",
                    "bone_id": 12,
                    "bone_overrides": {}
                }
            ],
            "links": {
                "thumbnail": "CharacterAttachments\/Item Thumbnails\/hands\/lo2\/thumb_lo2-gloves-13-sven.tif"
            }
        }
    ],
    "filters": [
        {
            "value": "lo2",
            "name": "Brand",
            "url": "url/to/file.tif"
        },
        {
            "value": "13/14",
            "name": "Season",
            "url": null
        }
    ],
    "rental_options": null,
    "storage": [
        {
            "key": "dog",
            "value": "yes"
        }
    ],
    "files": [
        {
            "url": "https://cdn.lootlocker.io/141/5f230b1e14614.txt",
            "tags": [
                "never",
                "gonna",
                "give",
                "you",
                "up"]
        }
    ],
    "data_entities": [
        "Your games custom data for this asset"
    ],
    "asset_candidate": {
        "created_by_player_id": 1234,
        "created_by_player_uid": "A1B2C3D4"
    },
    "drop_table_max_picks": null
}

Getting Asset Bone Information

curl -X GET "https://api.lootlocker.io/game/v1/asset/bones" \
  -H "x-session-token: your_token_here"

This call will return you all the default bones. If a binding overrides anything on a bone, it will be returned along with the binding.

Sample success response

{
  "success": true,
  "bones": [
    {
      "parameters": {
        "Rotation": "1,0,0,0",
        "Position": "-0.16281861,0.007631816,-0.93363667",
        "BoneName": "Bip01 L Foot",
        "Flags": "0",
        "Mass": "1.4",
        "Binding": "CharacterAttachments/bindings/lo2/lo2-bindings-13-pilen/lo2-bindings-13-pilen.cgf"
      },
      "id": "7",
      "name": "bindings_left"
    },
    {
      "parameters": {
        "Rotation": "1,0,0,0",
        "Position": "0.16281861,0.007631816,-0.93363667",
        "BoneName": "Bip01 R Foot",
        "Flags": "0",
        "Mass": "1.4",
        "Binding": "CharacterAttachments/bindings/lo2/lo2-bindings-13-pilen/lo2-bindings-13-pilen.cgf"
      },
      "id": "8",
      "name": "bindings_right"
    },
    {
      "parameters": {
        "Rotation": "0.70006877,0.0077114832,0.0037791394,0.71402371",
        "BoneName": "Bip01 Head",
        "Position": "0,0.24771199,0.8292712",
        "Flags": "0"
      },
      "id": "1",
      "name": "flashlight"
    },
    {
      "parameters": {
        "Rotation": "1,0,0,0",
        "BoneName": "Bip01 Head",
        "Position": "0,0,0",
        "Flags": "0",
        "Mass": "0.1"
      },
      "id": "3",
      "name": "goggles"
    },
    {
      "parameters": {
        "Rotation": "1,0,0,0",
        "BoneName": "Bip01 Head",
        "Position": "0,0,0",
        "Flags": "0"
      },
      "id": "4",
      "name": "gogglestrap"
    },
    {
      "parameters": {
        "Rotation": "1,0,0,0",
        "Position": "0,0,0",
        "BoneName": "Bip01 Head",
        "Flags": "0",
        "Mass": "0.5",
        "Binding": "CharacterAttachments/hats/lo2/lo2-hats-13-bovall/lo2-hats-13-bovall.cgf"
      },
      "id": "2",
      "name": "headwear"
    },
    {
      "parameters": {
        "Rotation": "0.80885416,-0.57089424,0.032788098,0.13696483",
        "Position": "-0.53078705,0.15658157,0.030430784",
        "BoneName": "Bip01 L Hand",
        "Flags": "0",
        "Mass": "0.2",
        "Binding": "CharacterAttachments/poles/lo2/lo2-pole-13-spara/lo2-pole-13-spara.cgf"
      },
      "id": "5",
      "name": "pole_left"
    },
    {
      "parameters": {
        "Rotation": "-0.80885416,0.57089424,0.032788098,0.13696483",
        "Position": "0.53078705,0.15658157,0.030430784",
        "BoneName": "Bip01 R Hand",
        "Flags": "0",
        "Mass": "0.2",
        "Binding": "CharacterAttachments/poles/lo2/lo2-pole-13-spara/lo2-pole-13-spara.cgf"
      },
      "id": "6",
      "name": "pole_right"
    },
    {
      "parameters": {
        "Rotation": "1,0,0,0",
        "Position": "-0.16281861,-0.023641124,-0.93918115",
        "BoneName": "Bip01 L Foot",
        "Flags": "0",
        "Mass": "2.5",
        "Binding": "CharacterAttachments/skis/lo2/lo2-skis-13-Spara/lo2-skis-13-Spara.cgf"
      },
      "id": "9",
      "name": "ski_left"
    },
    {
      "parameters": {
        "Rotation": "1,0,0,0",
        "Position": "0.16281861,-0.023641124,-0.93918115",
        "BoneName": "Bip01 R Foot",
        "Flags": "0",
        "Mass": "2.5",
        "Binding": "CharacterAttachments/skis/lo2/lo2-skis-13-Spara/lo2-skis-13-Spara.cgf"
      },
      "id": "10",
      "name": "ski_right"
    },
    {
      "parameters": {
        "Rotation": "1,0,0,0",
        "Position": "0.0015605614,-0.023641124,-0.93918115",
        "BoneName": "Bip01 L Foot",
        "Flags": "0",
        "Mass": "5",
        "Binding": "CharacterAttachments/Snowboards/snowboard_prototype.cgf"
      },
      "id": "11",
      "name": "snowboard"
    }
  ]
}

Getting Asset Information For One or More Assets

The id can also be a comma separated string for getting multiple assets: 16,17.

curl -X GET "https://api.lootlocker.io/game/v1/asset/16" \
  -H "x-session-token: your_token_here"

This endpoint returns data describing assets for game purposes, and it's a streamed response, just like when you call the Get All Assets endpoint.

Each returned asset has it own success status. It can be true or false, and if it's false, an error explaining what went wrong will also be returned, this object will also hold the ID of the asset you requested.

Sample success response

{
  "success": true
}

{
  "id": 916,
  "uuid": "a91adc11-4a7e-452e-be56-74a36bcfd87e",
  "name": "Sialia",
  "active": true,
  "price": 0,
  "sales_price": null,
  "shop_thumbnail": "",
  "context": "Map",
  "context_id": 3,
  "character_classes": [],
  "detachable": false,
  "updated": "Tue, 16 Jun 2015 08:38:19 +0000",
  "default_variation_id": 0,
  "default_loadouts": {
      "skier": true,
      "snowboarder": false
  },
  "description": "",
  "links": null,
  "storage": [
      {
          "key": "a key",
          "value": "the value"
      }
  ],
  "package_contents": null,
  "featured": false,
  "success": true
}

{
  "id": 917,
  "uuid": "8312744b-6817-41b1-a57e-2183dc10c111",
  "name": "Spawn_Event_ShrineTT6",
  "active": true,
  "price": 0,
  "sales_price": null,
  "shop_thumbnail": "",
  "context": "Spawn Point",
  "context_id": 4,
  "character_classes": [],
  "detachable": false,
  "updated": "Mon, 15 Jun 2015 16:19:05 +0000",
  "default_variation_id": 0,
  "default_loadouts": {
      "skier": true,
      "snowboarder": false
  },
  "description": "",
  "links": null,
  "storage": [
      {
          "key": "a key",
          "value": "the value"
      }
  ],
  "files": [
    {
        "url": "https://cdn.lootlocker.io/141/5f230b1e14614.txt",
        "tags": [
            "never",
            "gonna",
            "give",
            "you",
            "up"]
    }
  ],
  "package_contents": null,
  "featured": false,
  "data_entities": [
      "Your games custom data for this asset"
  ],
  "success": true
}

Sample failed request

{
    "success": true
}

{
    "success": false,
    "error": "No such asset",
    "asset_id": 916
}

{
    "id": 917,
    "uuid": "8312744b-6817-41b1-a57e-2183dc10c111",
    "name": "Spawn_Event_ShrineTT6",
    "active": true,
    "price": 0,
    "sales_price": null,
    "shop_thumbnail": "",
    "context": "Spawn Point",
    "context_id": 4,
    "character_classes": [],
    "detachable": false,
    "updated": "Mon, 15 Jun 2015 16:19:05 +0000",
    "default_variation_id": 0,
    "default_loadouts": {
        "skier": true,
        "snowboarder": false
    },
    "description": "",
    "links": null,
    "storage": [
        {
          "key": "a key",
          "value": "the value"
        }
    ],
    "files": [
        {
            "url": "https://cdn.lootlocker.io/141/5f230b1e14614.txt",
            "tags": [
                "never",
                "gonna",
                "give",
                "you",
                "up"]
        }
    ],
    "data_entities": [
        "Your games custom data for this asset"
    ],
    "package_contents": null,
    "featured": false,
    "success": true
}

Listing Favourite Assets

curl -X GET "https://api.lootlocker.io/game/v1/asset/favourites" \
  -H "x-session-token: your_token_here"

This call will simply list the current players favourite assets.

Example response

{
  "success": true,
  "favourites": [1, 2, 3, 4, 5]
}

Adding Favourite Assets

curl -X POST "https://api.lootlocker.io/game/v1/asset/258/favourite" \
  -H "x-session-token: your_token_here"

This will favourite the asset id that is placed in the url between asset and favourite. The response will be the same as from Listing Favourite Assets.

Removing Favourite Assets

curl -X DELETE "https://api.lootlocker.io/game/v1/asset/258/favourite" \
  -H "x-session-token: your_token_here"

This will remove the asset id that is placed in the url between asset and favourite from the favourite list. The response will be the same as from Listing Favourite Assets.

Asset Instances

Asset instances is what you will be working with when you have a player owned asset. A few actions can be taken on these instances, such as using the key/value storage to track distance traveled or deaths (etc) with one specific asset instance (also referred to as an item).

To call these endpoints, you will need to know the id of the instance you wish to interact with. You will find the instances you will have access to by calling the Get Inventory endpoint.

Getting All Key Value Pairs

curl -X GET "https://api.lootlocker.io/game/v1/asset/instance/storage" \
  -H "x-session-token: your_token_here"

This endpoint will return a streamed response with individual objects for each key/value pair.

Example Response

{
    "success": true,
}{
    "instance_id": 1234,
    "storage": {
        "id": 123,
        "key": "fruit",
        "value": "banana"
    }
}{
    "streamedObjectCount": 1
}

Getting All Key Value Pairs to an Instance

curl -X GET "https://api.lootlocker.io/game/v1/asset/instance/57613/storage" \
  -H "x-session-token: your_token_here"

When getting all key value pairs to an instance, you will receive an object with a success property. If this property holds a true value, you will also find a storage property, which will hold an array of key value pairs. In case of an error, the success property will hold a false value, and there will be an error property holding a string explaining what went wrong.

Example Response

{
  "success": true,
  "storage": [
    {
      "id": 1,
      "key": "distanceTraveled",
      "value": "118581"
    },
    {
      "id": 2,
      "key": "deaths",
      "value": "19"
    }
  ]
}

Getting A Key Value Pair By Id

curl -X GET "https://api.lootlocker.io/game/v1/asset/instance/57613/storage/1" \
  -H "x-session-token: your_token_here"

You can get a single key value pair by it's id by tacking the id of a pair on the url you used to get all key value pairs for an instance.

Example Response

{
  "success": true,
  "storage": [
    {
      "id": 1,
      "key": "distanceTraveled",
      "value": "45678"
    }
  ]
}

Creating A Key Value Pair

curl -X POST "https://api.lootlocker.io/game/v1/asset/instance/57613/storage" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d "{\"key\": \"distanceTraveled\", \"value\": \"1233\"}"

Creating a key value pair is done by sending a POST request to the same endpoint as you get the list from. There is currently no support for bulk creation of keys. You will have to send multiple requests.

Example Response

{
  "success": true,
  "storage": [
    {
      "id": 1,
      "key": "distanceTraveled",
      "value": "1233"
    }
  ]
}

Updating One Or More Key Value Pairs

curl -X PUT "https://api.lootlocker.io/game/v1/asset/instance/57613/storage" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d "{\"storage\": [{\"key\": \"distanceTraveled\", \"value\": \"45678\"}]}"

When you want to update the value of one or more keys, you can simply send a PUT request to the same endpoint as you would for creating a key value pair. The biggest difference is that this endpoint supports bulk requests, meaning the data format is a bit different in that it requires a main property (storage), which is an array holding objects of key value pairs.

Example Response

{
  "success": true,
  "storage": [
    {
      "id": 1,
      "key": "distanceTraveled",
      "value": "1233"
    }
  ]
}

Updating A Key Value Pair By Id

curl -X PUT "https://api.lootlocker.io/game/v1/asset/instance/57613/storage/1" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d "{\"key\": \"distanceTraveled\", \"value\": \"45678\"}"

When updating by id, both key and value are optional, but you must supply at least one of them. When updating by id, you can change the key, and keep the value if you wish. The response from this call will only return the affected key value pair.

Example Response

{
  "success": true,
  "storage": [
    {
      "id": 1,
      "key": "distanceTraveled",
      "value": "45678"
    }
  ]
}

Delete A Key Value Pair

curl -X DELETE "https://api.lootlocker.io/game/v1/asset/instance/57613/storage/1" \
  -H "x-session-token: your_token_here"

Deleting a key value pair is done by sending a DELETE request with the id of the pair you want to delete. The response will be the same as calling Getting All Key Value Pairs To An Instance.

Example response

{
  "success": true,
  "storage": [
    {
      "id": 2,
      "key": "deaths",
      "value": "19"
    }
  ]
}

Inspect a Loot Box

curl -X GET "https://api.lootlocker.io/game/v1/asset/instance/57613/inspect" \
  -H "x-session-token: your_token_here"

Asset instances with the type set to loot box can be inspected, to see what assets the player might possibly get when opening them.

You are supplied with the weight of the assets in this call. You can use that to display the chance that a player will get an asset, or to simulate it in a carousel. Sum the weights to know the total lots, and then you have a weight in sum(weights) chance of getting a specific asset. For more information see the article by Peter Kelly on weighted random selection.

Example response

{
  "success": true,
  "contents": [
    {
      "asset_id": 4,
      "asset_variation_id": null,
      "asset_rental_option_id": 11,
      "weight": 200
    },
    {
      "asset_id": 7,
      "asset_variation_id": 5,
      "asset_rental_option_id": null,
      "weight": 2
    },
    {
      "asset_id": 7,
      "asset_variation_id": null,
      "asset_rental_option_id": null,
      "weight": 40
    }
  ]
}

Open a Loot Box

curl -X PUT "https://api.lootlocker.io/game/v1/asset/instance/57613/open" \
  -H "x-session-token: your_token_here"

Asset instances with the type set to loot box can be opened, using this endpoint. Once you call this endpoint, the Loot Box will be removed from the players inventory, and a new asset will be added to the inventory, with the acquisition_source set to grant_loot_box. You will be asked to check the grant notifications to see which asset was granted.

Example response

{
  "success": true,
  "check_grant_notifications": true
}

In a 10000 iteration test we ran, we got the following results:

Asset Weight Times received Predicted chance Actual chance
1 1 59 0.55% 0.59%
2 80 4417 44.20% 44.17%
3 100 5524 55.25% 55.24%
Sums 181 10000 100% 100%

For more information see the article by Peter Kelly on weighted random selection.

Asset Instance Progressions

Asset Instance progression API is used to track progressions of asset instances.

You can also add or subtract points, reset or delete asset instance progressions using this API.

Starting an asset instance progression is as easy as just starting to add points.

Get Asset Instance Progressions

curl -X GET "https://api.lootlocker.io/game/player/assets/instances/1/progressions?count=10&after=01GJN6J46DM00Z88WR225Y9P77"
-H "x-session-token: your_token_here"

Get list of progressions the asset instance is currently on. Results are always sorted by ID.

URL Structure

/game/player/assets/instances/<asset_instance_id>/progressions

Example Response

{
  "pagination": {
    "next_cursor": null,
    "previous_cursor": null,
    "total": 2
  },
  "items": [
  {
    "id": "01GJN6J46DM00Z88WR225Y9P77",
    "progression_key": "summer_battle_pass",
    "progression_name": "Summer Battle Pass",
    "step": 1,
    "points": 200,
    "previous_threshold": 0,
    "next_threshold": 500,
    "last_level_up": null
  },
  {
    "id": "01GJN6JGK3AV0N8YJ9GHSCJ4D3",
    "progression_key": "spring_battle_pass",
    "progression_name": "Spring Battle Pass",
    "step": 3,
    "points": 1300,
    "previous_threshold": 1000,
    "next_threshold": 2000,
    "last_level_up": "2022-11-24T16:12:41Z"
  }
  ]
}

URL Parts

Part Description
asset_instance_id ID of the asset instance

Query Parameters:

Field Description
after Cursor for pagination, a cursor will be returned in the response
count Number of progressions returned per page. Max 500 is allowed

Get Asset Instance Progression By Key

curl -X GET "https://api.lootlocker.io/game/player/assets/instances/1/progressions/summer_battle_pass"
-H "x-session-token: your_token_here"

Get a single asset instance progression by Key.

URL Structure

/game/player/assets/instances/<asset_instance_id>/progressions/<progression_key>

Example Response

{
  "id": "01GJN6J46DM00Z88WR225Y9P77",
  "progression_key": "summer_battle_pass",
  "progression_name": "Summer Battle Pass",
  "step": 1,
  "points": 200,
  "previous_threshold": 0,
  "next_threshold": 500,
  "last_level_up": null
}

URL Parts

Part Description
progression_key Key of the progression
asset_instance_id ID of the asset instance

Add points to an asset instance progression

curl -X POST "https://api.lootlocker.io/game/player/assets/instances/1/progressions/summer_battle_pass/points/add" \
-H "x-session-token: your_token_here" \
-H "Content-Type: application/json" \
-d "{\"amount\": 1000 }"

Adds specified amount of points to an asset instance progression. If the asset instance is not on that progression it will be automatically started.

If there was a "level up", awarded_tiers fields will contain acquired rewards.

URL Structure

/game/player/assets/instances/<asset_instance_id>/progressions/<progression_key>/points/add

Example Response

{
  "id": "01GJN6J46DM00Z88WR225Y9P77",
  "progression_key": "summer_battle_pass",
  "progression_name": "Summer Battle Pass",
  "step": 3,
  "points": 1200,
  "previous_threshold": 1000,
  "next_threshold": 2000,
  "last_level_up": "2022-11-24T16:12:41Z",
  "awarded_tiers": [
    {
      "step": 2,
      "points_threshold": 500,
      "rewards": {
        "progression_points_rewards": [
          {
            "progression_name": "paragon",
            "progression_key": "Paragon",
            "amount": 100
          }
        ],
        "progression_reset_rewards": [
          {
            "progression_name": "bonus_xp",
            "progression_key": "Bonus XP"
          }
        ],
        "asset_rewards": [
          {
            "asset_id": 2,
            "asset_variation_id": null,
            "asset_rental_option_id": null
          }
        ],
        "currency_rewards": [
          {
            "currency_name": "Gold",
            "currency_code": "GLD",
            "amount": "100"
          }
        ]
      }
    },
    {
      "step": 3,
      "points_threshold": 1000,
      "rewards": {
        "progression_points_rewards": [],
        "progression_reset_rewards": [],
        "asset_rewards": [],
        "currency_rewards": []
      }
    }
  ]
}

URL Parts

Part Description
progression_key Key of the progression
asset_instance_id ID of the asset instance

Available input fields

amount is required.

Field Description
amount Amount of points to be added to the asset instance progression.

Subtract points from an asset instance progression

curl -X POST "https://api.lootlocker.io/game/player/assets/instances/1/progressions/spring_battle_pass/points/subtract" \
-H "x-session-token: your_token_here" \
-d "{\"amount\": 10 }" \
-H "Content-Type: application/json"

Subtracts specified amount of points from an asset instance progression. Progression cannot go down a level, the points will be set to the previous_threshold if too many points are being subtracted.

URL Structure

/game/player/assets/instances/<asset_instance_id>/progressions/<progression_key>/points/subtract

Example Response

{
    "id": "01GJN6JGK3AV0N8YJ9GHSCJ4D3",
    "progression_key": "spring_battle_pass",
    "progression_name": "Spring Battle Pass",
    "step": 3,
    "points": 1290,
    "previous_threshold": 1000,
    "next_threshold": 2000,
    "last_level_up": "2022-11-24T16:12:41Z",
    "awarded_tiers": []
}

URL Parts

Part Description
progression_key Key of the progression
asset_instance_id ID of the asset instance

Available input fields

amount is required.

Field Description
amount Amount of points to be subtracted from the asset instance progression.

Reset an asset instance progression

curl -X POST "https://api.lootlocker.io/game/player/assets/instances/1/progressions/spring_battle_pass/reset" \
-H "x-session-token: your_token_here" \
-H "Content-Type: application/json"

Resets an asset instance progression. This endpoint sets the asset instance progression points to 0, so it still shows up as an active progression.

URL Structure

/game/player/assets/instances/<asset_instance_id>/progressions/<progression_key>/reset

Example Response

{
    "id": "01GJN6JGK3AV0N8YJ9GHSCJ4D3",
    "progression_key": "spring_battle_pass",
    "progression_name": "Spring Battle Pass",
    "step": 1,
    "points": 0,
    "previous_threshold": 0,
    "next_threshold": 1000,
    "last_level_up": null,
    "awarded_tiers": []
}

URL Parts

Part Description
progression_key Key of the progression
asset_instance_id ID of the asset instance

Delete an asset instance progression

curl -X DELETE "https://api.lootlocker.io/game/player/assets/instances/1/progressions/spring_battle_pass" \
-H "x-session-token: your_token_here" \
-H "Content-Type: application/json"

Deletes an asset instance progression. It won't show up in progression list for that asset instance.

URL Structure

/game/player/assets/instances/<asset_instance_id>/progressions/<progression_key>

Example Response

This endpoint will not have a body, being a 204 No Content HTTP response.

URL Parts

Part Description
progression_key Key of the progression
asset_instance_id ID of the asset instance

User Generated Content

With User Generated Content (UGC) your game client can upload Asset Candidates to LootLocker which can be turned into Assets to get the full power of LootLocker's Asset functionality.

Asset Candidates are promoted to Assets once they are marked as complete and have passed moderation. Moderation can be disabled if you do not distribute UGC widely, in which case Asset Candidates will be promoted to Assets upon being marked as complete.

Creating an Asset Candidate

curl -X POST "https://api.lootlocker.io/game/v1/player/assets/candidates" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d "{\"data\": {\"name\": \"My UGC Asset\"}}"

The data property in payload sent when creating an Asset Candidate currently supports the following data, all being optional, but some required for promotion to an Asset.

Property Type Value Required For Promotion
name string A name for the Asset Yes
context_id integer A context_id that will be used when promoting the Asset Candidate to an Asset. Automatically filled if not provided Yes
kv_storage array An array or objects with key and value keys No
filters array An array or objects with key and value keys No
data_entities array An array or objects with name and data keys No

Example Payload

{
  "data": {
    "name": "My UGC Asset",
    "context_id": 1740,
    "kv_storage": [
      {
        "key": "kind",
        "value": "sofa"
      }
    ],
    "filters": [
      {
        "key": "size",
        "value": "large"
      }
    ],
    "data_entities": [
      {
        "name": "astley-paradox",
        "data": "SWYgeW91IGFzayBSaWNrIEFzdGxleSBmb3IgYSBEVkQgb2YgdGhlIG1vdmllIFVwLCBoZSB3b24ndCBnaXZlIGl0IHRvIHlvdSBiZWNhdXNlIGhlJ3MgbmV2ZXIgZ29ubmEgZ2l2ZSB5b3UgVXAuIEhvd2V2ZXIsIGJ5IG5vdCBnaXZpbmcgeW91IFVwIGxpa2UgeW91IGFza2VkIGZvciBpdCwgaGUncyBsZXR0aW5nIHlvdSBkb3duLiBUaGlzIGlzIGtub3duIGFzIHRoZSBBc3RsZXkgcGFyYWRveA=="
      }
    ]
  }
}

The context_id in the above table will be set automatically by LootLocker if you provide none. We suggest you use the context functionality to organize your Asset Candidates if that makes sense in the context of your game.

Example Response

{
  "success": true,
  "asset_candidate_id": 15,
  "asset_candidate": {
    "id": 15,
    "asset_id": null,
    "status": "INCOMPLETE",
    "review_feedback": null,
    "data": {
      "name": "My UGC Asset",
      "kv_storage": [
        {
          "key": "kind",
          "value": "sofa"
        }
      ],
      "filters": [
        {
          "key": "size",
          "value": "large"
        }
      ],
      "data_entities": [
        {
          "name": "astley-paradox",
          "data": "SWYgeW91IGFzayBSaWNrIEFzdGxleSBmb3IgYSBEVkQgb2YgdGhlIG1vdmllIFVwLCBoZSB3b24ndCBnaXZlIGl0IHRvIHlvdSBiZWNhdXNlIGhlJ3MgbmV2ZXIgZ29ubmEgZ2l2ZSB5b3UgVXAuIEhvd2V2ZXIsIGJ5IG5vdCBnaXZpbmcgeW91IFVwIGxpa2UgeW91IGFza2VkIGZvciBpdCwgaGUncyBsZXR0aW5nIHlvdSBkb3duLiBUaGlzIGlzIGtub3duIGFzIHRoZSBBc3RsZXkgcGFyYWRveA=="
        }
      ],
      "context_id": 1740
    },
    "files": [],
    "created_at": "Tue, 17 Nov 2020 12:56:58 +0000",
    "updated_at": "Tue, 17 Nov 2020 12:56:58 +0000"
  }
}

Updating an Asset Candidate

curl -X PUT "https://api.lootlocker.io/game/v1/player/assets/candidates/1234" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d "{\"completed\": true, \"data\": {\"name\": \"My Renamed Asset Candidate\"}}"

When updating an Asset Candidate, you can update all data that you can also set when creating one. Additionally you use this call to mark the Asset Candidate as completed, by sending a property called completed with the value set to boolean true.

Any data property sent along will replace the entirety of that property on the Asset Candidate, so make sure that you send everything you want to store, and not just what's changed.

Example Response

{
  "success": true,
  "asset_candidate": {
    "id": 15,
    "asset_id": 6763,
    "status": "APPROVED",
    "review_feedback": null,
    "data": {
      "name": "My UGC Asset",
      "kv_storage": [
        {
          "key": "kv-test",
          "value": "great success"
        }
      ],
      "filters": [
        {
          "key": "filter-test",
          "value": "great success"
        }
      ],
      "data_entities": [
        {
          "name": "Entity test",
          "data": "flergen dergen hergen"
        }
      ],
      "context_id": 1740
    },
    "files": [],
    "created_at": "Tue, 17 Nov 2020 12:56:58 +0000",
    "updated_at": "Tue, 17 Nov 2020 12:58:25 +0000"
  }
}

Once an Asset Candidate has been marked as completed, it will enter the moderation queue or be directly promoted to an Asset if moderation is disabled for your game. Once this has happened you can no longer update it.

Deleting an Asset Candidate

curl -X DELETE "https://api.lootlocker.io/game/v1/player/assets/candidates/1234" \
  -H "x-session-token: your_token_here"

Deleting Asset Candidates can be done by ID, and only while the Asset Candidate haven't yet been promoted to an Asset.

Example Response

{ "success": true }

Listing Asset Candidates

curl -X GET "https://api.lootlocker.io/game/v1/player/assets/candidates" \
  -H "x-session-token: your_token_here"

You can retrieve all Asset Candidates belonging to the current player, by issuing a call to this endpoint. If an Asset Candidate have been promoted to an Asset, the Asset's ID will be set in the property asset_id.

Example Response

{
  "success": true,
  "asset_candidates": [
    {
      "id": 3876,
      "asset_id": 6737,
      "status": "APPROVED",
      "review_feedback": null,
      "data": {
        "name": "My UGC Asset",
        "kv_storage": [
          {
            "key": "kind",
            "value": "sofa"
          }
        ],
        "filters": [
          {
            "key": "size",
            "value": "large"
          }
        ],
        "data_entities": [
          {
            "name": "astley-paradox",
            "data": "SWYgeW91IGFzayBSaWNrIEFzdGxleSBmb3IgYSBEVkQgb2YgdGhlIG1vdmllIFVwLCBoZSB3b24ndCBnaXZlIGl0IHRvIHlvdSBiZWNhdXNlIGhlJ3MgbmV2ZXIgZ29ubmEgZ2l2ZSB5b3UgVXAuIEhvd2V2ZXIsIGJ5IG5vdCBnaXZpbmcgeW91IFVwIGxpa2UgeW91IGFza2VkIGZvciBpdCwgaGUncyBsZXR0aW5nIHlvdSBkb3duLiBUaGlzIGlzIGtub3duIGFzIHRoZSBBc3RsZXkgcGFyYWRveA=="
          }
        ],
        "context_id": 1740
      },
      "files": [
        {
          "id": 5,
          "url": "https://cdn.lootlocker.io/......",
          "size": 69919,
          "name": "my-ugc-asset-thumbnail.png",
          "purpose": "PRIMARY_THUMBNAIL"
        }
      ],
      "created_at": "Mon, 26 Oct 2020 08:48:34 +0000",
      "updated_at": "Mon, 26 Oct 2020 10:28:03 +0000"
    }
  ]
}

You will notice a context_id in the Asset Candidate data. You can assign contexts to your Asset Candidates, but if you do not, LootLocker will automatically create a User Generated Content context and put the context in that context.

The status property can be used to know what the current status of an Asset Candidate is. The table below lists the possible statuses:

Status Meaning
INCOMPLETE The Asset Candidate has not yet been marked as complete
DECLINED The Asset Candidate was rejected in moderation (see potential feedback in review_feedback)
PENDING The Asset Candidate is awaiting moderation
APPROVED The Asset Candidate is approved and usable by players in the game (asset_id references the derived Asset, and is null for any other status)

Getting a single Asset Candidate

curl -X GET "https://api.lootlocker.io/game/v1/player/assets/candidates/1234" \
  -H "x-session-token: your_token_here"

You can also fetch just a single asset candidate by it's ID. The response will be a single object, but otherwise identical to listing Asset Candidates.

Example Response

{
  "success": true,
  "asset_candidate": {
    "id": 15,
    "asset_id": 6763,
    "status": "APPROVED",
    "review_feedback": null,
    "data": {
      "name": "My UGC Asset",
      "kv_storage": [
        {
          "key": "kv-test",
          "value": "great success"
        }
      ],
      "filters": [
        {
          "key": "filter-test",
          "value": "great success"
        }
      ],
      "data_entities": [
        {
          "name": "Entity test",
          "data": "flergen dergen hergen"
        }
      ],
      "context_id": 1740
    },
    "files": [],
    "created_at": "Tue, 17 Nov 2020 12:56:58 +0000",
    "updated_at": "Tue, 17 Nov 2020 12:58:25 +0000"
  }
}

Adding Files to Asset Candidates

curl -L -X POST 'https://api.lootlocker.io/game/v1/player/assets/candidates/1234/file' \
  -H "x-session-token: your_token_here" \
  -F 'file=@/path/to/file.ext' \
  -F 'purpose=PRIMARY_THUMBNAIL'

When adding a file to an Asset Candidate you need to supply the file in a property called file along with a purpose to let LootLocker know what to do with the file.

File Purposes

Purpose Used For
PRIMARY_THUMBNAIL The Primary Thumbnail shown in the LootLocker interface for moderation and curation purposes
THUMBNAIL Any extra images you want to expose to the LootLocker interface
FILE Any file you need to represent the content in your game client

Example Response

{ "success": true }

Removing Files from an Asset Candidate

curl -X DELETE "https://api.lootlocker.io/game/v1/player/assets/candidates/1234/file/1234" \
  -H "x-session-token: your_token_here"

Deleting a file is done by referencing the Asset Candidate and the File by their respective ID's in the URL.

Example Response

{ "success": true }

Missions

Getting All Missions

curl -X GET "https://api.lootlocker.io/game/v1/missions" \
  -H "x-session-token: your_token_here"

When getting all missions, you will receive data to set up the missions in the map too. You only get this data (checkpoints), if the player has access to this mission. You can check if a player has access to a mission by looking at the boolean player_access. The segment_time field that will be returned with each checkpoint is the time-between-checkpoint, which you can use to let the player know how they're doing compared to their last run. As you can see in the example, the segment_time property is not guaranteed to be there. It will however most likely be there for all checkpoints in one mission, unless the mission has been updated since the player last played it.

The best_goal property will hold a string with the name of the best goal the player have attained. If they have never played this mission or never reached a goal, it will be null.

As you can see in the example JSON, goals have an assets attribute. This is an array containing objects of assets that will be rewarded the first time the player reaches this goal. See example structure under the gold goal.

{
    "success": true,
    "missions": [
        {
            "mission_id": 1,
            "asset_id": 912,
            "rounds": 0,
            "round_length": "0",
            "difficulty_name": null,
            "difficulty_multiplier": null,
            "difficulty_color": "336699",
            "difficulty_id": 1,
            "goals": {
                "gold": {
                    "goal": "00:20:00",
                    "points": "400",
                    "assets": [
                        {
                            "variation_id": 1,
                            "asset": {...}
                        }
                    ]
                },
                "silver": {
                    "goal": "00:30:00",
                    "points": "200",
                    "assets": []
                },
                "bronze": {
                    "goal": "00:35:00",
                    "points": "100",
                    "assets": []
                }
            },
            "checkpoints": [
              {
                "index": 1,
                "time": 18510,
                "your_key": "your value",
                "your_second_key": "your second value"
              },{
                "index": 2,
                "your_key": "your value",
                "your_second_key": "your second value"
              }
            ],
            "player_access": true,
            "best_goal": "bronze"
        }
    ]
}

Getting A Single Mission

curl -X GET "https://api.lootlocker.io/game/v1/mission/42" \
  -H "x-session-token: your_token_here"

This endpoint is very similar to the Getting All Missions endpoint, in that it returns the same mission structure, but instead of a property called missions holding an array of missions, there is a property called mission, holding just one mission.

{
  "success": true,
  "mission": {
    "mission_id": 1,
    "asset_id": 912,
    "rounds": 0,
    "round_length": "0",
    "difficulty_name": null,
    "difficulty_multiplier": null,
    "difficulty_color": "336699",
    "difficulty_id": 1,
    "goals": {
      "gold": {
        "goal": "00:20:00",
        "points": "400",
        "assets": [
          {
            "variation_id": 1,
            "asset": "Full asset representation, as returned everywhere else."
          }
        ]
      },
      "silver": {
        "goal": "00:30:00",
        "points": "200",
        "assets": []
      },
      "bronze": {
        "goal": "00:35:00",
        "points": "100",
        "assets": []
      }
    },
    "checkpoints": [
      {
        "index": 1,
        "time": 18510,
        "your_key": "your value",
        "your_second_key": "your second value"
      },
      {
        "index": 2,
        "your_key": "your value",
        "your_second_key": "your second value"
      }
    ],
    "player_access": true,
    "best_goal": "bronze"
  }
}

Starting Mission

curl -X POST "https://api.lootlocker.io/game/v1/mission/1/start" \
  -H "x-session-token: your_token_here"

When starting a mission, you need to call this endpoint. From this endpoint you will get a signature back, which you need to use to sign the mission end call.

{
  "success": true,
  "signature": "86f7e437faa5a7fce15d1ddcb9eaeaea377667b8"
}

Finishing Mission

curl -X POST "https://api.lootlocker.io/game/v1/mission/1/end" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d "{\"signature\": \"eee411109a229046154bc9d75265a9ccb23a3a9c\", \"payload\": {\"finish_time\": \"02:23:255\", \"finish_score\": \"125\", \"checkpoint_times\": [{\"index\": 1, \"time\": 571613}]}}"

When finishing the mission, you send a POST request to this endpoint. Your payload will hold data that's needed to calculate the score. You should calculate the score on your end, but you should correct your result to what you get from the response of this request, as that is what will be used in the backend.

If your mission is time based, you can send along checkpoint times, referenced as times. These are reported in milliseconds, and as a difference between two checkpoints only, summing these up should equal the total time of the mission. The backend will automatically store these for returning when loading missions. The data will only be updated if the total time is better than what's on file.

{
  "success": true,
  "score": 450,
  "check_grant_notifications": true
}

The check_grant_notifications field serves the same function as in the authentication call, meaning that if it's true, you should check the player asset notification endpoint for new notifications. You can do so immediately in this case, unlike the authentication call.

You do not have to send both finish_time and finish_score in calls, if you instead prefer to keep track of which type of mission is using what kind of goal, but you can simply just send both.

Signing Your Mission

Signing has to be done by concatenating the JSON string, the signature and the players backend id, and then hash it using SHA1.

# Assuming the three parts are
# 1: JSON = {"finish_time":"02:23:255","finish_score":"125"}
# 2: Signature = 86f7e437faa5a7fce15d1ddcb9eaeaea377667b8
# 3: player_id = 1234

sha1({"finish_time":"02:23:255","finish_score":"125"}86f7e437faa5a7fce15d1ddcb9eaeaea377667b81234) = 0689b28cc7fbd97e454ee0f4315b76abbabb4d4c

The order should be JSON string signature player_id.

The first part of the concatenated string is the JSON bit. That should only contain the object inside the payload property.

The second part is the signature you obtained from the Starting Mission endpoint.

The third part should be the player_id that you get when starting the session.

Once you've concatenated the three parts and hashed the resulting string, you should put it in a JSON object with the key signature, along side the payload property.

Drop Tables

Compute and Lock Drop Table

curl -X POST "https://api.lootlocker.io/game/v1/player/droptables/2/compute" \
  -H "x-session-token: your_token_here"

When you wish to evaluate a drop table and lock the drops from it in place, you call this endpoint. The response will hold information on the assets that are dropped, and can be picked up using the Pick endpoint.

The response is kept light to minimise resource usage, but if you need the full representation of the asset, you can include a GET style parameter in the url ?asset_details=true, and an additional asset property will be returned, with the full asset representation.

If you use tags with your drop tables, you can include a tag to only include groups and drops tagged with this tag in the calculation. The tag is included by adding it as a GET style parameter: ?tag=skeleton.

Example Response

{
  "success": true,
  "items": [
    {
      "asset_id": 520,
      "asset_variation_id": null,
      "asset_rental_option_id": null,
      "id": 3
    }
  ]
}

The ID in the URL is the instance_id of the drop table asset from the players inventory.

Once a drop table has been computed and locked, there is a 24 hour guarantee that the pick endpoint will work. After this period, the drop table asset instance and it's locked drops may will be removed from the players inventory.

Pick Drops from Drop Table

curl -X POST "https://api.lootlocker.io/game/v1/player/droptables/2/pick" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d "{\"picks\": [3]}"

When picking the drops to claim from a locked drop table, you send a payload along with the request, containing the ID's of the drops from the Compute endpoint. This payload has the key picks which contain an array of the ID's you want to pick. If you want to pick up nothing, you can send an empty array.

The response from this request contains the full asset of all the picked drops. See Getting Asset List for the full structure.

Example Response

{
    "success": true,
    "items": [
        {
            "instance_id": 487,
            "variation_id": null,
            "rental_option_id": null,
            "quantity": 1,
            "asset": {...}
        }
    ]
}

Maps

Getting All Maps

curl -X GET "https://api.lootlocker.io/game/v1/maps" \
  -H "x-session-token: your_token_here"

Getting all maps will return the simplest representation of a map, simply providing you with an asset_id to get the name, thumbnail etc. Maps also contain the spawn points.

Example response

{
  "success": true,
  "maps": [
    {
      "map_id": 1,
      "asset_id": 938,
      "spawn_points": [
        {
          "asset_id": 966,
          "position": null,
          "rotation": null,
          "cameras": [
            {
              "position": "12958181",
              "rotation": "9591885818"
            }
          ],
          "player_access": false
        },
        {
          "asset_id": 967,
          "position": "9157757101045",
          "rotation": "958176717818238",
          "cameras": [
            {
              "position": "12958181",
              "rotation": "9591885818"
            }
          ],
          "player_access": true
        }
      ],
      "player_access": false
    },
    {
      "map_id": 2,
      "asset_id": 950,
      "spawn_points": [
        {
          "asset_id": 966,
          "position": null,
          "rotation": null,
          "cameras": [
            {
              "position": "12958181",
              "rotation": "9591885818"
            }
          ],
          "player_access": false
        },
        {
          "asset_id": 967,
          "position": "9157757101045",
          "rotation": "958176717818238",
          "cameras": [
            {
              "position": "12958181",
              "rotation": "9591885818"
            }
          ],
          "player_access": true
        }
      ],
      "player_access": false
    },
    {
      "map_id": 3,
      "asset_id": 965,
      "spawn_points": [
        {
          "asset_id": 966,
          "position": null,
          "rotation": null,
          "cameras": [
            {
              "position": "12958181",
              "rotation": "9591885818"
            }
          ],
          "player_access": false
        },
        {
          "asset_id": 967,
          "position": "9157757101045",
          "rotation": "958176717818238",
          "cameras": [
            {
              "position": "12958181",
              "rotation": "9591885818"
            }
          ],
          "player_access": true
        }
      ],
      "player_access": true
    }
  ]
}

🕸️ Legacy Purchasing

Only some platforms support purchasing with hard currency. The below table provides an overview

Platform Supports Hard Currency Purchasing
Steam Yes
PSN Yes
iOS Yes
Android Yes

Purchase Call

Sending a request to this endpoint with asset information, will facilitate a purchase. If your game uses soft currency, it will check the players account balance and grant the assets to the player if there is coverage. If there is not coverage, an error will be returned.

There are two different kinds of purchases you can perform. A rental and a standard purchase. When doing a standard purchase, you only need the asset_id and potentially the variation_id properties. When buying a rental asset, you will be required to send at least the asset_id and rental_option_id parameters. The rental_option_id value is obtained from the assets call, just like the asset_id and the variation_id. To activate a rental, see Activating A Rental Asset

Normal purchase example

curl -X POST "https://api.lootlocker.io/game/v1/purchase" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d "[{\"asset_id\": 56, \"variation_id\": 130},{\"asset_id\": 380, \"variation_id\": 616}]"

If your game does not use soft currency, or the assets you are buying are soft currency, the purchase will behave a few different ways depending on what platform the user is on:

Platform Action
Steam An overlay will be opened, asking the player to pay with their Steam Wallet.
PSN For PSN you will have had to initialize the purchase with the SDK for the PS4 first, and then call this endpoint to tell LootLocker to consume the entitlemnt on PSN.
iOS You have to complete an iOS In-App Purchase before calling the purchase endpoint in LootLocker. See iOS In-App Purchases for more information.
Android Similar to iOS, you have to complete an In-App Pruchase before calling the purchase endpoint in LootLocker. See Android In-App Purchases for more information.

Rental example

curl -X POST "https://api.lootlocker.io/game/v1/purchase" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d "[{\"asset_id\": 56, \"variation_id\": 130, \"rental_option_id\": 47}]"

You will get an order_id in the response. This ID should be used to poll the order status until you get a final answer from it. See the polling order status endpoint

The response will let you know if any form of overlay have been opened. Keep in mind, only if you have success = true and overlay = false can you safely assume that the purchase has been successful. If overlay is true, you should check the order status to know the status of the order. Once you know the purchase was successful you should issue a call to the player inventory endpoint to update the client inventory data.

The external_identifiers field in the asset responses, is either null or an object, letting you know how to identify this same asset on other platforms. In the given examples PSN is used, and CRED01 is the entitlementLabel/entitlementId on Sony's side. Use this to know what credit package a player has bought through their servers when selecting which asset to purchase.

Example response, with no overlay opened

{
  "success": true,
  "overlay": false,
  "order_id": 583
}

iOS In-App Purchases

iOS In-App Purchase verification example

curl -X POST "https://api.lootlocker.io/game/v1/purchase" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d "[{\"receipt_data\": \"base64 encoded app store receipt\"}]"

In-App Purchases on iOS are different from other purchases in LootLocker in the way that they don't take asset information, but instead requires a receipt from Apple that LootLocker will then verify and map to the correct asset information. This receipt is returned when reading Bundle.main.appStoreReceiptURL from your application.

For any assets that should be purchasable multiple times, you should use consumable IAP's on Apples side, and once you have a successful purchase from LootLocker, call finishTransaction on the transaction in the client, to let Apple know to consume the purchase.

Once the request returns successfully you should issue a call to the player inventory endpoint and/or the currency balance endpoint to update the client inventory and balance data.

Example response for iOS In-App Purchase

{
  "success": true,
  "overlay": false,
  "order_id": 583
}

Android In-App Purchases

Android In-App Purchase verification example

curl -X POST "https://api.lootlocker.io/game/v1/purchase" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d "[{\"asset_id\": 1234, \"purchase_token\": \"purchase_token_supplied_by_google_play_store\"}]"

Purchases on Android are slightly different from other purchases, in that they take a purchase_token property besides the asset information. In the example here, we are buying in-game currency, which only requires an asset_id and the token. The purchase_token is obtained through the Google Play store, when performing an In-App Purchase.

Once the request returns successfully you should issue a call to the player inventory endpoint and/or the currency balance endpoint to update the client inventory and balance data.

Polling Order Status

curl -X GET "https://api.lootlocker.io/game/v1/purchase/23" \
  -H "x-session-token: your_token_here"

This call will let you know the current status of an order. If you get a response that is considered final, you should issue a call to the player inventory endpoint if you're in a context where the inventory might change.

Example response

{
  "success": true,
  "status": "closed"
}

The following statuses can currently be returned:

Status Final Description
open No The order is being processed
closed Yes The order have been processed successfully
refunded Yes The order has been refunded
canceled Yes The order has been canceled
failed Yes The order failed

Get Order Details

curl -X GET "https://api.lootlocker.io/game/v1/purchase/23/details" \
  -H "x-session-token: your_token_here"

This endpoint lets you inspect an order and see what products is contained, as well as the order status. For a description of order statuses, please see the table under Polling Order Status.

If you do not want to return the products, you can add a flag to the url that removes them: ?no_products=true, in which case the products property will be null.

Example Response

{
    "success": true,
    "order_status": "succeeded",
    "products": [
        {
            "instance_id": 458,
            "variation_id": null,
            "rental_option_id": null,
            "acquisition_source": "purchase_unit",
            "asset": {...}
        }
    ]
}

Get Order Details By Platform Transaction ID

curl -X GET "https://api.lootlocker.io/game/v1/purchase/transaction/1000000673097863/details" \
  -H "x-session-token: your_token_here"

This endpoint is identical to Get Order Details, except that instead of the order id, you can use the First Party Platforms Transaction ID.

The response is identical as well.

Activating A Rental Asset

curl -X POST "https://api.lootlocker.io/game/v1/asset/instance/57613/activate" \
  -H "x-session-token: your_token_here"

Once you have purchased a rental asset, you need to activate the rental for it to become available for the player. This endpoint achieves that.

The successful response from this endpoint, will contain just one property, time_left, which is seconds left until the rental expires. You should keep a timer running to deactivate the asset for the player once it runs out.

Example response

{
  "success": true,
  "time_left": 86400
}

Trigger Events

Execute Trigger

curl -X POST "https://api.lootlocker.io/game/v1/player/trigger" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"your trigger name here\"}"

Trigger events can be configured through the Admin API, or in the LootLocker Management Console. There you can set rewards for triggering an event and so forth.

Rewards can be either XP or assets (It can also be both). If assets have been granted, the endpoint will return the granted assets in the granted_assets property, in the standard full asset object format.

As you can see in the example response, XP is a little more complicated, as it will return in the same format as the Submit Score endpoint.

All of the properties will always be present

Example response

{
    "success": true,
    "check_grant_notifications": true,
    "xp": {
        "previous": 1234,
        "current": 2468
    },
    "levels": [
        {
            "level": 1,
            "xp_threshold": 1000
        },
        {
            "level": 2,
            "xp_threshold": 3000
        },
        {
            "level": 3,
            "xp_threshold": 6000
        }
    ],
    "granted_assets": [
        {...}
    ]
}

Listing Triggered Trigger Events

curl -X GET "https://api.lootlocker.io/game/v1/player/triggers" \
  -H "x-session-token: your_token_here"

This endpoint lists the triggers that a player have already completed.

Use this list to know which triggers to not call from the game client.

Example Response

{
  "success": true,
  "triggers": [
    "enterArea.area_east_sub_1",
    "enterArea.area_east_sub_10",
    "enterArea.area_east_sub_11",
    "enterArea.area_east_sub_2"
  ]
}

Collectables

Collectables and triggers are very similar functionalities. The difference is that collectables are nested in 3 layers (Collectable, Groups and Items). Each entity in can have a reward that's triggered when all nested entities are completed (for items this is when the item is collected).

Getting Collectables

curl -X GET "https://api.lootlocker.io/game/v1/collectable" \
  -H "x-session-token: your_token_here"

This endpoint will return all the collectables a game has set up. It will hold a set of Collectables, with Groups inside which in turn contain Items. Items are what you collect as a player. The Groups and the Collectable are containers, that serve to give a segmented completion percentage and to give rewards to the player at different completion stages.

Each level (Collectables, Groups and Items) can contain rewards for the player. These rewards are contained in rewards for each item. An empty array means no rewards. There is a flag grants_all_rewards, which signifies if the rewards will be all granted to the player, or if one of the rewards will be randomly selected for the reward. Each reward contains a full representation of an asset, along with the asset_variation_id or asset_rental_option_id that will be granted to the player.

Even collected Items are returned, with a boolean collected set to true. This is done to make it easier to remove them from your world, give them a different look, or make sure you do not collect them again.

Additionally there is a boolean just_collected to let you know if this collectable item was collected in a call issued to the Collecting an Item endpoint. It will always be false when requesting the list of collectables, and only be true if the call was successful in collecting an item.

Example response

{
    "success": true,
    "collectables": [
        {
            "name": "CarsDriven",
            "groups": [
                {
                    "name": "SUVs",
                    "completion_percentage": 50,
                    "items": [
                        {
                            "name": "Sporty",
                            "collected": true,
                            "rewards": [],
                            "grants_all_rewards": false,
                            "just_collected": false
                        },
                        {
                            "name": "Practical",
                            "collected": false,
                            "rewards": [],
                            "grants_all_rewards": false,
                            "just_collected": false
                        }
                    ],
                    "rewards": [],
                    "grants_all_rewards": false
                },
                {
                    "name": "Bugs",
                    "completion_percentage": 0,
                    "items": [
                        {
                            "name": "Dune",
                            "collected": false,
                            "rewards": [
                                {
                                    "asset": {...},
                                    "asset_variation_id": 7010,
                                    "asset_rental_option_id": null
                                }
                            ],
                            "grants_all_rewards": true,
                            "just_collected": false
                        }
                    ],
                    "rewards": [],
                    "grants_all_rewards": false
                }
            ],
            "completion_percentage": 33,
            "rewards": [],
            "grants_all_rewards": false
        }
    ]
}

Collecting an Item

curl -X POST "https://api.lootlocker.io/game/v1/collectable" \
  -H "x-session-token: your_token_here" \
  -H "Content-Type: application/json" \
  -d "{\"slug\": \"CarsDriven.Bugs.Dune\"}"

Collecting an Item is done by calling this endpoint with a payload equal to the slug of the Item.

The slug is a combination of the name of the Collectable, the Group and the Item. Simply concatenate them with a . as a separator. In the example we're collecting the Item Dune in the Group Bugs that belongs to the Collectable CarsDriven.

Once an Item is collected, you will get a response back identical to the one you get from Getting Collectables, with the addition of a field at the root level called check_grant_notifications. If this field is true, you should check the players player asset grant notifications.

Messages

Get Messages

curl -X GET "https://api.lootlocker.io/game/v1/messages" \
  -H "x-session-token: your_token_here"

The messages Game System allows you to send messages to your players, such as news and promotions.

Messages are somewhat personalized for the player, in that they has a new property that tells if the message is new since the players last session.

Example Response

{
  "success": true,
  "messages": [
    {
      "title": "Whiteridge has opened!",
      "published_at": "2017-09-08 09:36:25",
      "body": "Welcome to Whiteridge! The small mountain town with lots of stuff for your skiing pleasure...",
      "summary": "Today we're releasing a new level called Whiteridge.\r\n\r\nWhiteridge is an urban level with lots of jumps and features to hit.",
      "category": "levels",
      "alert": true,
      "new": true,
      "action": "",
      "image": "https://url/to/file.dds"
    }
  ]
}

Miscellaneous

Server Time

curl -X GET "https://api.lootlocker.io/game/ping" \
  -H "x-session-token: your_token_here" \
  -H "LL-Version 2021-03-01"

Using this endpoint you can obtain a timestamp that will always be the same for all your clients.

The format of the timestamp returned is RFC3339, with milliseconds.

Example Response

{
  "date": "2022-02-16T10:04:20.155Z"
}

Currency

Get Currency By Code

curl --location 'https://api.lootlocker.io/game/currency/code/{currency_code}' \
-H 'x-session-token: {x-session-token}'

Response

{
  "created_at": "2023-09-18T12:05:37Z",
  "id": "01HAM2X360PD565H51JA8717JZ",
  "name": "Gold",
  "code": "gld",
  "game_id": 23647,
  "published": false,
  "game_api_writes_enabled": false,
  "published_at": null
}

HTTP Request

GET https://api.lootlocker.io/game/currency/code/{currency_code}

Parameters

Parameter Type Description
currency_code string required The code of the currency you want to retrieve.

List Currencies

curl --location 'https://api.lootlocker.io/game/currencies/' \
-H 'x-session-token: {x-session-token}'

Response

{
  "currencies": [
    {
      "created_at": "2023-09-18T12:05:37Z",
      "id": "01HAM2X360PD565H51JA8717JZ",
      "name": "Gold",
      "code": "gld",
      "game_id": 23647,
      "published": false,
      "game_api_writes_enabled": false,
      "published_at": null
    },
    {
      "created_at": "2023-09-18T12:05:45Z",
      "id": "01HAM2XAGWGK6ZETTXS1AWM6K9",
      "name": "Wood",
      "code": "wod",
      "game_id": 23647,
      "published": false,
      "game_api_writes_enabled": false,
      "published_at": null
    }
  ]
}

HTTP Request

GET https://api.lootlocker.io/game/currencies/

List Denominations By Currency

curl --location --request GET 'https://api.lootlocker.io/game/currency/code/{currency_code}/denominations' \
-H 'x-session-token: {x-session-token}'

Response

{
  "denominations": [
    {
      "created_at": "2023-09-18T12:05:37Z",
      "id": "01HAM2X361N2EH1BKYYEWXTKNH",
      "currency": "01HAM2X360PD565H51JA8717JZ",
      "name": "Coin",
      "value": 1
    }
  ]
}

HTTP Request

GET https://api.lootlocker.io/game/currency/code/{currency_code}/denominations

Parameters

Parameter Type Description
currency_code string required The Currency Code of the currency you want to retrieve denominations for.

Purchasing

Make A Purchase (In Game Only)

curl --location 'https://api.lootlocker.io/game/purchase' \
-H 'x-session-token: {x-session-token}' \
-H 'Content-Type: application/json' \
--data '{
    "wallet_id": "01HB65TP64HA67EQ9F4HYXRQDE",
    "items": [
        {
            "catalog_listing_id": "01HCF7DAZYBXTS70H9SABJF604",
            "quantity": 1
        }
    ]
}'

Response

{
  "success": true
}

HTTP Request

POST https://api.lootlocker.io/game/purchase

Parameters

Parameter Type Description
wallet_id string required The id of the wallet to purchase from.
items array required An array of items to purchase containing the catalog listing id and quantity.

In-app purchasing

Supported stores:

Google Play Store

Apple App Store

Google Play Store

Example

curl -X POST "https://api.lootlocker.io//game/store/google/redeem" \
-H 'x-session-token: {x-session-token}' \
-H 'Content-Type: application/json' \
--data '
{
    "product_id": "sword_1",
    "purchase_token": "kfilbepmffaloanbcshlmchc.AO-J1OwK_M0U71Tf-1k9Imt4AvEijOHLcZtedYVazQX2sVk1rABq10CF8gjHQg70X1oCSbh6EGsvmP1zxk-3jnQeCAH6g3qmUTvfUjcIXDJV4-J7ooV-fuI"
}'

This endpoint redeems the purchased items (assets, progression points/resets, currencies etc.) to a player (or optionally a character) that were purchased through the Google Play Store.

Parameters

Parameter Description
product_id The product id you configured in the the Google Play Console.
purchase_token The purchase token received from Google Play Store on a successful purchase.
character_id (Optional) Used when a purchase should be redeemed for a character.

Apple App Store

Example

curl -X POST "https://api.lootlocker.io//game/store/apple/redeem" \
-H 'x-session-token: {x-session-token}' \
-H 'Content-Type: application/json' \
--data '
{
    "transaction_id": "1200200316432494",
    "sandboxed": "true"
}'

This endpoint redeems the purchased items (assets, progression points/resets, currencies etc.) to a player (or optionally a character) that were purchased through the Apple App Store.

Parameters

Parameter Description
transaction_id Transaction id received from Apple App Store on a successful purchase.
character_id (Optional) Used when a purchase should be redeemed for a character.
sandboxed (Optional) Used for testing.

Balances

List Balances

curl --location 'https://api.lootlocker.io/game/balances/wallet/{wallet_id}' \
-H 'x-session-token: {x-session-token}'

Response

{
  "balances": [
    {
      "created_at": "2023-09-25T12:43:07Z",
      "amount": "100",
      "currency": {
        "code": "gld",
        "name": "Gold",
        "id": "01HAM2X360PD565H51JA8717JZ"
      },
      "wallet_id": "01HB65TP64HA67EQ9F4HYXRQDE"
    }
  ]
}

HTTP Request

GET https://api.lootlocker.io/game/balances/wallet/{wallet_id}

Parameters

Parameter Type Description
wallet_id string required The id of the wallet to retrieve balances for.

Get Wallet

curl --location 'https://api.lootlocker.io/game/wallet/{wallet_id}' \
-H 'x-session-token: {x-session-token}'

Response

{
  "holder_id": "01HCCQS1H0217TSM8QXQXKQVXS",
  "id": "01HCCQZS8DQR1VFK73W9K6P29X",
  "type": "player"
}

HTTP Request

GET https://api.lootlocker.io/game/wallet/{wallet_id}

Parameters

Parameter Type Description
wallet_id string required The id of the wallet to retrieve.

Get Wallet For Holder

curl --location 'https://api.lootlocker.io/game/wallet/holder/{holder_id}' \
-H 'x-session-token: {x-session-token}'

Response

{
  "holder_id": "01HCCQS1H0217TSM8QXQXKQVXS",
  "id": "01HCCQZS8DQR1VFK73W9K6P29X",
  "type": "player"
}

HTTP Request

GET https://api.lootlocker.io/game/wallet/holder/{holder_id}

Parameters

Parameter Type Description
holder_id string required The id of the holder to retrieve the wallet for.

Create New Wallet

curl --location 'https://api.lootlocker.io/game/wallet' \
-H 'x-session-token: {x-session-token}' \
--data '{
    "holder_id": "01HBGDFRG4XPXNQ174B3FVFMCD",
    "holder_type": "player"
}'

Response

{
  "wallet_id": "01HBGDG2NBDEFYXT8Q03M80RV3"
}

HTTP Request

POST https://api.lootlocker.io/game/wallet

Parameters

Parameter Type Description
holder_id string required The id of the holder to create the wallet for.
holder_type string required The type of the holder to create the wallet for (one of player, character).

Credit Balance

curl --location 'https://api.lootlocker.io/game/balances/credit' \
-H 'x-session-token: {x-session-token}' \
--data '{
    "amount": "1",
    "wallet_id": "01HB65TP64HA67EQ9F4HYXRQDE",
    "currency_id": "01HAM2X360PD565H51JA8717JZ"
}'

Response

{
  "created_at": "2023-09-25T12:43:07Z",
  "amount": "101",
  "currency": {
    "code": "gld",
    "name": "Gold",
    "id": "01HAM2X360PD565H51JA8717JZ"
  },
  "wallet_id": "01HB65TP64HA67EQ9F4HYXRQDE"
}

HTTP Request

POST https://api.lootlocker.io/game/balances/credit

Parameters

Parameter Type Description
amount string required The amount to credit.
wallet_id string required The id of the wallet to credit.
currency_id string required The id of the currency to credit.

Debit Balance

curl --location 'https://api.lootlocker.io/game/balances/debit' \
-H 'x-session-token: {x-session-token}' \
--data '{
    "amount": "1",
    "wallet_id": "01HB65TP64HA67EQ9F4HYXRQDE",
    "currency_id": "01HAM2X360PD565H51JA8717JZ"
}'

Response

{
  "created_at": "2023-09-25T12:43:07Z",
  "amount": "100",
  "currency": {
    "code": "gld",
    "name": "Gold",
    "id": "01HAM2X360PD565H51JA8717JZ"
  },
  "wallet_id": "01HB65TP64HA67EQ9F4HYXRQDE"
}

HTTP Request

POST https://api.lootlocker.io/game/balances/debit

Parameters

Parameter Type Description
amount string required The amount to debit.
wallet_id string required The id of the wallet to debit.
currency_id string required The id of the currency to debit.

Catalogs

List Catalogs For Game

curl --location 'https://api.lootlocker.io/game/catalogs/' \
-H 'x-session-token: {x-session-token}'

Response

{
  "catalogs": [
    {
      "created_at": "2023-09-18T12:05:31Z",
      "name": "Some Catalog",
      "key": "some_catalog",
      "game_id": 23647,
      "id": "01HAM2WX9BZ2WS16A3XWTWT0V9",
      "deleted_at": null
    }
  ]
}

HTTP Request

GET https://api.lootlocker.io/game/catalogs/

List Catalog Items By Key

curl --location 'https://api.lootlocker.io/game/catalog/key/{key}/prices' \
-H 'x-session-token: {x-session-token}'

Response

{
  "catalog": {
    "id": "01HCCQNGVYPV3XMKXN82FHBERN",
    "name": "Test Catalog",
    "key": "test_catalog"
  },
  "entries": [
    {
      "created_at": "2023-10-10T12:06:04Z",
      "entity_kind": "asset",
      "entity_name": "Sword",
      "prices": [
        {
          "amount": "123",
          "display_amount": "123 GLD",
          "currency_code": "gld",
          "currency_name": "Gold",
          "price_id": "01HCCQNQKQA30E4TZWTESNZX5N",
          "currency_id": "01HBTE31EVTATJN7HS2DH84H7J"
        }
      ],
      "entity_id": "01HAM2XM04TMAGAYA8KTKT6QTE",
      "grouping_key": "01HCCQNQKQA30E4TZWTGHFZGZ4",
      "purchasable": false
    }
  ],
  "assets_details": [
    {
      "name": "Sword",
      "variation_id": null,
      "rental_option_id": null,
      "legacy_id": 298778,
      "id": "01HAM2XM04TMAGAYA8KTKT6QTE",
      "grouping_key": "01HCCQNQKQA30E4TZWTGHFZGZ4",
      "thumbnail": null
    }
  ],
  "progression_points_details": [],
  "progression_resets_details": [],
  "currency_details": [],
  "pagination": {
    "previous_cursor": null,
    "next_cursor": null,
    "total": 1
  }
}

HTTP Request

GET https://api.lootlocker.io/game/catalog/key/{key}/prices?cursor={cursor}&per_page={per_page}

Parameters

Parameter Type Description
key string required The key of the catalog to list items from.
cursor string optional The cursor to use for pagination.
per_page number optional The number of items to return per page.

Errors

Errors are hinted with HTTP Status codes. 200 is OK, the rest that we're using is listed below here. You should be able to handle all of these in your integration.

Error Code Meaning
400 Bad Request -- Your request has an error
402 Payment Required -- Payment failed. Insufficient funds, etc.
401 Unauthorized -- Your session_token is invalid
403 Forbidden -- You do not have access
404 Not Found
405 Method Not Allowed
406 Not Acceptable -- Purchasing is disabled
409 Conflict -- Your state is most likely not aligned with the servers.
429 Too Many Requests -- You're being limited for sending too many requests too quickly.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're either offline for maintenance, or an error that should be solvable by calling again later was triggered.

Deprecations

When the API changes and an endpoints reaches the end of it's life, it will send a X-Endpoint-Deprecated: true header with each response, until it's taken out of service. A list of currently deprecated endpoints will also be maintained here, along with their EOL date, which is 6 months after they have been deprecated.

If the below table is empty, there aren't currently any deprecations.

Endpoint Request Type EOL Replaced By