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.
Sign in With Apple Game Center
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 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 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 |
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 |
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 |
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:
- Each file can be a maximum of 5MB.
- There can be a maximum of 50 files per player.
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
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 |
---|