Introduction

Welcome to the LootLocker Server 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.io, or swing by our Discord Server and talk to us directly.

Intended Usage

The inteded use for this API is for communication between LootLocker and a trusted server that you manage. This can be either a dedicated game server, or some other trusted server that will perform actions on behalf of a player.

The Server API is not as fully featured as the Admin and Game API's yet. We expand it as new use cases present themselves or our users request functionality from it. If you need something in the Server API that isn't here yet, please do reach out on Discord or by email and let us know.

Getting Started

This API needs to be enabled, before you can use it. You enable it by creating an API key in the LootLocker Web Console under API. Once enabled you can start making requests immediately.

Versioning

When sending requests to the LootLocker Server API, you must inform the API which version you want to use, using the HTTP header LL-Version.

curl -X POST "https://api.lootlocker.io/server/session" \
  -H "LL-Version: 2021-03-01"

Currently the only version that exists is 2021-03-01, but as more versions will exist in the future, LootLocker needs to know what version of the API you're using so we can guarantee that we will not break your client in the future.

Pagination

For any paginated endpoints, we follow the following convention.

curl -X GET "https://api.lootlocker.io/server/assets?count=200&after=5320"

Pagination is controlled using two url parameters, the first being count, and the second being after.

count can be a number between 1 and 200. If the number is outside of this range, it will default to 50. If the parameter is omitted, it will also default to 50. These defaults and limits may differ between calls. If they do, it will be mentioned for the specific call.

{
  "total": 517,
  "items": []
}

after is the id of the last asset you recieved in the previous call. After is optional, as you will never have an id to pass in on your first call.

The response from any paginated call will always contain a total field, letting you know how many total items to expect.

Response and Error Codes

The LootLocker Server API follows standard HTTP response status codes for hinting errors to clients.

The default response code is 200 which means OK. Other response codes used by LootLocker can be seen in the table below.

Code	Meaning	Explanation
400	Bad Request	Something is wrong with the request sent by the client. This is usually Developer Error, and the error is in the `error` property in the response.
401	Unauthorized	You have either not registered a session, or it has expired.
404	Not Found	The entity requested was not found.
500	Internal Server Error	An unknown error occured in LootLocker. Retry, and if the error persists, contact us with the `error_id` from the response.

Authentication

Registering a Server Session

curl -X POST "https://api.lootlocker.io/server/session" \
    -H "LL-Version: 2021-03-01" \
    -H "x-server-key: f31aq540cb18e5ca0ee911c8284de5b5b93d6a01" \
    -H "Content-Type: application/json" \
    -d "{\"game_version\": \"1.0.0.0\"}"

When registering a session, you must provide the Server API Key in a header named x-server-key, and the latest game version your server is compatible with, in the request body as a JSON object.

If using legacy server keys, you can can optionally send the property is_development. This will start the session for the development environment.

The response will be a JSON object.

{
  "token": "unR7YZAsf7aXxMP8BXj8fTP1fevarOmajhWabRuM"
}

The successful response will return a token which you must use for any following requests. This token has a lifetime of 1 hour, but can be extended by periodically calling the endpoint for Mantaining a Server Session.

{
  "error": "No game_version parameter provided"
}

Maintaining a Server Session

curl -X GET "https://api.lootlocker.io/server/ping" \
    -H "LL-Version: 2021-03-01" \
    -H "x-auth-token: unR7YZAsf7aXxMP8BXj8fTP1fevarOmajhWabRuM"

To keep your servers session alive, you should call this endpoint at least once per hour, to extend your tokens lifetime.

{
  "pong": 1612905462
}

Assets

Get Assets to Game

curl -X GET "https://api.lootlocker.io/server/assets" \
    -H "LL-Version: 2021-03-01"

To retrieve all assets for your game, call this endpoint. The response will be similar to the one the Game API recieves. For a full explanation of the data structure, please see the Game API Documentation.

{
  "total": 33,
  "items": [
    {
      "id": 434,
      "uuid": "64ba8834-e95c-46be-9de7-3acbef07001b",
      "name": "Monster Truck",
      "active": true,
      "purchasable": true,
      "price": 100,
      "sales_price": null,
      "display_price": "100",
      "context": "Heavy Chassis",
      "context_id": 51821,
      "unlocks_context": null,
      "detachable": false,
      "updated": "Mon, 11 Jan 2021 15:22:18 +0000",
      "marked_new": null,
      "default_variation_id": 362,
      "default_loadouts": {
        "Light Vehicle": false,
        "Heavy Vehicle": false
      },
      "description": "",
      "links": {
        "thumbnail": "https://cdn.lootlocker.io/...."
      },
      "storage": [
        {
          "key": "my key",
          "value": "my value"
        }
      ],
      "rarity": null,
      "popular": false,
      "popularity_score": 0,
      "package_contents": null,
      "unique_instance": false,
      "external_identifiers": null,
      "rental_options": null,
      "filters": [],
      "files": [],
      "data_entities": [],
      "hero_equip_exceptions": {},
      "asset_candidate": null,
      "variations": [
        {
          "id": 362,
          "name": "Default",
          "primary_color": null,
          "secondary_color": null,
          "links": {
            "thumbnail": "https://cdn.lootlocker.io/...."
          }
        }
      ],
      "featured": false,
      "context_locked": false,
      "initially_purchasable": true,
      "drop_table_max_picks": null
    }
  ]
}

This call is paginated.

Asset Instances

Getting All Key Value Pairs to an Instance

curl -X GET "https://api.lootlocker.io/server/player/1234/assets/instances/57613/storage"

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.

{
    "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/server/player/1234/assets/instances/57613/storage/1"

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.

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

Creating A Key Value Pair

curl -X POST "https://api.lootlocker.io/server/player/1234/assets/instances/57613/storage"
  -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.

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

Updating One Or More Key Value Pairs

curl -X PUT "https://api.lootlocker.io/server/player/1234/assets/instances/57613/storage"
  -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.

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

Updating A Key Value Pair By Id

curl -X PUT "https://api.lootlocker.io/server/player/1234/assets/instances/57613/storage/1"
  -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.

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

Delete A Key Value Pair

curl -X DELETE "https://api.lootlocker.io/server/player/1234/assets/instances/57613/storage/1"

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.

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

Player Names

Lookup multiple player names using IDs

curl -G "https://api.lootlocker.io/server/players/lookup/name" \
    -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 \
    -H "LL-Version: 2021-03-01" \
    -H "x-auth-token: fh2ubeotOwpJOyNLSMw14f6OLqavFJK2Ts3Ev889"

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

{
  "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"
    }
  ]
}

Player Inventory

Get Player Inventory

curl -X GET "https://api.lootlocker.io/server/player/1234/inventory" \
    -H "LL-Version: 2021-03-01" \
    -H "x-auth-token: unR7YZAsf7aXxMP8BXj8fTP1fevarOmajhWabRuM"

List a players default characters inventory using this endpoint. The number in the URL is the LootLocker ID of the player.

This call is paginated.

{
    "total": 1,
    "items": [
        {
            "instance_id": 4,
            "variation_id": null,
            "rental_option_id": null,
            "acquisition_source": "grant_default_loadout",
            "asset": {...},
            "rental": {
                "is_rental": false,
                "time_left": null,
                "duration": null,
                "is_active": null
            }
        }
    ]
}

Get Universal Inventory (Global Assets)

curl -X GET "https://api.lootlocker.io/server/inventory/universal" \
    -H "LL-Version: 2021-03-01" \
    -H "Content-Type: application/json" \
    -H "x-auth-token: unR7YZAsf7aXxMP8BXj8fTP1fevarOmajhWabRuM" \

This endpoint will return the current list of universal assets for your game. These assets are equippable in both the Game and Server APIs, using the equip endpoints, with the asset_id and asset_variation_id or asset_rental_id.

{
    "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
            }
        }
    ]
}

Add Asset to Player Inventory

curl -X POST "https://api.lootlocker.io/server/player/1234/inventory" \
    -H "LL-Version: 2021-03-01" \
    -H "Content-Type: application/json" \
    -H "x-auth-token: unR7YZAsf7aXxMP8BXj8fTP1fevarOmajhWabRuM" \
    -d "{\"asset_id\": 442, \"asset_variation_id\": 370}"

Use this endpoint to grant an asset to a player as you see fit. Besides asset_variation_id you can also send asset_rental_option_id if you are using rental assets. If you do not send either of the two, the asset will either be granted with the default variation, or if it doesn't use variations, it will be granted as is.

The response of this API call will return the granted assets, which you can use to merge into the assets you already have for this player.

{
    "items": [
        {
            "instance_id": 464,
            "variation_id": 370,
            "acquisition_source": "grant_server_api",
            "asset": {...},
            "rental": {
                "is_rental": false,
                "time_left": null,
                "duration": null,
                "is_active": null
            }
        }
    ]
}

Alter Player Inventory

curl -X PATCH "https://api.lootlocker.io/server/player/1234/inventory" \
    -H "LL-Version: 2021-03-01" \
    -H "Content-Type: application/json" \
    -H "x-auth-token: unR7YZAsf7aXxMP8BXj8fTP1fevarOmajhWabRuM" \
    -d "{\"add\": [{\"asset_id\": 1, \"asset_variation_id\": 2}], \"remove\": [1,2,3,4]}"

Use this endpoint to remove, add or both assets to a players inventory.

The add property contents is an array of objects identical to the one you send in the Add Asset to Player Inventory endpoint.

The remove property contents is an array of Instance ID's from the players inventory.

Both add and remove are optional properties.

The response returns the successfully added assets, and the Instance ID's that were removed from the player. See the example response.

{
    "added": [
        {
            "instance_id": 599,
            "variation_id": null,
            "rental_option_id": null,
            "quantity": 1,
            "asset": {
                "id": 442,
                "name": "Buggy",
                "active": true,
                "purchasable": true,
                "price": 100,
                "sales_price": null,
                "display_price": null,
                "context": "Light Chassis",
                "unlocks_context": null,
                "detachable": false,
                "updated": "Mon, 11 Jan 2021 15:22:18 +0000",
                "marked_new": null,
                "default_variation_id": 370,
                "default_loadouts": {
                    "Light Vehicle": false,
                    "Heavy Vehicle": false
                },
                "description": "",
                "links": {
                    "thumbnail": "https://ll-game-files.s3.eu-north-1.amazonaws.com/sample-game/buggy.png"
                },
                "storage": [],
                "rarity": null,
                "popular": false,
                "popularity_score": 0,
                "package_contents": null,
                "unique_instance": false,
                "external_identifiers": null,
                "rental_options": null,
                "filters": [],
                "files": [],
                "data_entities": [],
                "hero_equip_exceptions": {},
                "asset_candidate": null,
                "drop_table_max_picks": null,
                "variations": [
                    {
                        "id": 370,
                        "name": "Default",
                        "primary_color": null,
                        "secondary_color": null,
                        "links": {
                            "thumbnail": "https://ll-game-files.s3.eu-north-1.amazonaws.com/sample-game/buggy.png"
                        }
                    }
                ]
            }
        }
    ],
    "removed": [
        509
    ]
}

Get Player Loadout

curl -X GET "https://api.lootlocker.io/server/player/1234/loadout" \
    -H "LL-Version: 2021-03-01" \
    -H "x-auth-token: unR7YZAsf7aXxMP8BXj8fTP1fevarOmajhWabRuM"

This endpoint will return the players default characters loadout.

{
    "items": [
        {
            "variation_id": 370,
            "instance_id": 464,
            "mounted_at": "2021-02-24T09:37:42+00:00",
            "asset": {... },
            "rental": {
                "is_rental": false,
                "time_left": null,
                "duration": null,
                "is_active": null
            }
        }
    ]
}

Equip Asset for Player Loadout

curl -X POST "https://api.lootlocker.io/server/player/1234/loadout" \
    -H "LL-Version: 2021-03-01" \
    -H "Content-Type: application/json" \
    -H "x-auth-token: unR7YZAsf7aXxMP8BXj8fTP1fevarOmajhWabRuM" \
    -d "{\"instance_id\": 464}"

This endpoint will equip an asset instance to the players default character. The response is a full representation of the default characters loadout.

In the case of Universal Assets, you can send the body as in the Universal Asset example on the right. Rental assets also work with rental_option_id instead of asset_variation_id.

curl -X POST "https://api.lootlocker.io/server/player/1234/loadout" \
    -H "LL-Version: 2021-03-01" \
    -H "Content-Type: application/json" \
    -H "x-auth-token: unR7YZAsf7aXxMP8BXj8fTP1fevarOmajhWabRuM" \
    -d "{\"asset_id\": 464, \"asset_variation_id\": 5817}"

{
    "items": [
        {
            "variation_id": 370,
            "instance_id": 464,
            "mounted_at": "2021-02-24T09:37:42+00:00",
            "asset": {...},
            "rental": {
                "is_rental": false,
                "time_left": null,
                "duration": null,
                "is_active": null
            }
        }
    ]
}

Unequip Asset for Player Loadout

curl -X DELETE "https://api.lootlocker.io/server/player/1234/loadout/5678" \
    -H "LL-Version: 2021-03-01" \
    -H "x-auth-token: unR7YZAsf7aXxMP8BXj8fTP1fevarOmajhWabRuM"

This endpoint will unequip an asset instance for the players default character. The response is a full representation of the default characters loadout.

{
    "items": [
        {
            "variation_id": 370,
            "instance_id": 464,
            "mounted_at": "2021-02-24T09:37:42+00:00",
            "asset": {...},
            "rental": {
                "is_rental": false,
                "time_left": null,
                "duration": null,
                "is_active": null
            }
        }
    ]
}

Player Persistent Storage

Get Persistent Storage

curl -X GET "https://api.lootlocker.io/server/players/storage?player_ids=1,2"

This endpoint can be used to read player storage one or more players, by sending the Player ID's in the GET style parameter player_ids, as a comma delimited list.

{
    "items": [
        {
            "player_id": 1,
            "items": [
                {
                    "key": "my-key",
                    "value": "my-value-2",
                    "is_public": false
                }
            ]
        },
        {
            "player_id": 2,
            "items": []
        }
    ]
}

Update Persistent Storage

curl -X PATCH "https://api.lootlocker.io/server/players/storage" \
    -H "LL-Version: 2021-03-01" \
    -H "Content-Type: application/json" \
    -H "x-auth-token: fh2ubeotOwpJOyNLSMw14f6OLqavFJK2Ts3Ev889" \
    -d "{\"payload\": [{\"player_id\": 1, \"sets\": [{\"key\": \"mykey\", \"value\": \"myvalue\", \"is_public\": true, \"order\": 1}]}]}"

Using this endpoint you can update player storage for a specific player, much like the Game API allows.

The order property is required, but can be any sequence of numbers you like. The later keys just need to have a higher number than the early ones. This is used to deduplicate keys on the backend so you do not need to worry about that.

is_public is optional and will allow others to read storage sets with it set to true.

{
    "items": [
        {
            "player_id": 1,
            "items": [
                {
                    "key": "my-key",
                    "value": "my-value-2",
                    "is_public": false
                }
            ]
        }
    ]
}

Delete Persistent Storage

curl -X DELETE "https://api.lootlocker.io/server/players/storage?player_ids=1,2,3&keys=a,b,c" \
    -H "LL-Version: 2021-03-01" \
    -H "Content-Type: application/json" \
    -H "x-auth-token: fh2ubeotOwpJOyNLSMw14f6OLqavFJK2Ts3Ev889"

This endpoint will allow you to delete storage by keys to multiple players. Any key sent in will be deleted for all players provided.

The response is an empty body unless an error occurs. The response code is 204 No Content.

In the event of an error, the response will look as the example given here.

{
    "error": "Failed to delete entries"
}

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.

List Files for Player

curl -X GET "https://api.lootlocker.io/server/players/{player_id}/files" \
    -H "LL-Version: 2021-03-01" \
    -H "x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab"

This endpoint will list all files currently associated with the player.

{
    "items": [
        {
            "id": 840,
            "name": "filename.extension",
            "size": 3105898,
            "purpose": "SAVE_GAME",
            "url": "https://cdn.lootlocker.io/...",
            "url_expires_at": "2022-05-05T19:48:58.672801683Z",
            "created_at": "2022-05-05T13:48:55Z"
        }
    ]
}

Get File By ID for Player

curl -X GET "https://api.lootlocker.io/server/players/{player_id}/files/{file_id}" \
    -H "LL-Version: 2021-03-01" \
    -H "x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab"

This endpoint will let you get a file by it's ID.

{
    "id": 840,
    "name": "filename.extension",
    "size": 3105898,
    "purpose": "SAVE_GAME",
    "url": "https://cdn.lootlocker.io/...",
    "url_expires_at": "2022-05-05T19:50:14.904973036Z",
    "created_at": "2022-05-05T13:48:55Z"
}

Delete File for Player

curl -X DELETE "https://api.lootlocker.io/server/players/{player_id}/files/{file_id}" \
    -H "LL-Version: 2021-03-01" \
    -H "x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab"

Using this endpoint, you can delete files for players.

The response from this endpoint is a 204 No Content, response with no body.

Upload File for Player

curl -X POST 'https://api.lootlocker.io/server/players/{player_id}/files' \
    -H 'x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab' \
    -H "LL-Version: 2021-03-01" \
    -F 'file=@"path/to/your/file"' \
    -F 'purpose="save_game"'

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.

{
    "id": 840,
    "name": "filename.extension",
    "size": 3105898,
    "purpose": "SAVE_GAME",
    "url": "https://cdn.lootlocker.io/...",
    "url_expires_at": "2022-05-05T19:48:55.07519941Z",
    "created_at": "2022-05-05T13:48:55.069835878Z"
}

Characters and Heroes

Get Player Characters

curl -X GET "https://api.lootlocker.io/server/player/1234/characters"

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

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

Get Inventory to Character

curl -X GET "https://api.lootlocker.io/server/player/1234/character/5678/inventory"

This call allows you to get the inventory for a specific character belonging to a player.

This call is paginated.

{
    "total": 1,
    "items": [
        {
            "instance_id": 4,
            "variation_id": null,
            "rental_option_id": null,
            "acquisition_source": "grant_default_loadout",
            "asset": {...},
            "rental": {
                "is_rental": false,
                "time_left": null,
                "duration": null,
                "is_active": null
            }
        }
    ]
}

Get Character Loadout

curl -X GET "https://api.lootlocker.io/server/player/1234/characters/5678/loadout"

Get a characters full loadout.

{
    "items": [
        {
            "variation_id": 370,
            "instance_id": 464,
            "mounted_at": "2021-02-24T09:37:42+00:00",
            "asset": {...},
            "rental": {
                "is_rental": false,
                "time_left": null,
                "duration": null,
                "is_active": null
            }
        }
    ]
}

Equip Asset for Character Loadout

curl -X POST "https://api.lootlocker.io/server/player/1234/character/5678/loadout" \
    -H "LL-Version: 2021-03-01" \
    -H "Content-Type: application/json" \
    -H "x-auth-token: unR7YZAsf7aXxMP8BXj8fTP1fevarOmajhWabRuM" \
    -d "{\"instance_id\": 464}"

This endpoint will equip an asset instance to a specific character. The response is a full representation of the characters loadout.

In the case of Universal Assets, you can send the body as in the Universal Asset example on the right. Rental assets also work with rental_option_id instead of asset_variation_id.

curl -X POST "https://api.lootlocker.io/server/player/1234/character/5678/loadout" \
    -H "LL-Version: 2021-03-01" \
    -H "Content-Type: application/json" \
    -H "x-auth-token: unR7YZAsf7aXxMP8BXj8fTP1fevarOmajhWabRuM" \
    -d "{\"asset_id\": 464, \"asset_variation_id\": 5817}"

{
    "items": [
        {
            "variation_id": 370,
            "instance_id": 464,
            "mounted_at": "2021-02-24T09:37:42+00:00",
            "asset": {...},
            "rental": {
                "is_rental": false,
                "time_left": null,
                "duration": null,
                "is_active": null
            }
        }
    ]
}

Unequip Asset for Character Loadout

curl -X DELETE "https://api.lootlocker.io/server/player/1234/character/5678/loadout/464" \
    -H "LL-Version: 2021-03-01" \
    -H "Content-Type: application/json" \
    -H "x-auth-token: unR7YZAsf7aXxMP8BXj8fTP1fevarOmajhWabRuM"

This endpoint will unequip an asset instance for a character. The response is a full representation of the characters loadout.

{
    "items": [
        {
            "variation_id": 370,
            "instance_id": 465,
            "mounted_at": "2021-03-01T19:08:31+00:00",
            "asset": {...},
            "rental": {
                "is_rental": false,
                "time_left": null,
                "duration": null,
                "is_active": null
            }
        }
    ]
}

Get Player Heroes

curl -X GET "https://api.lootlocker.io/server/player/1/heroes"

Use this endpoint to list all heroes to a player.

{
    "items": [
        {
            "id": 6,
            "hero_id": 33,
            "instance_id": 4,
            "hero_name": "Little Blue",
            "character_name": "Medium Yellow",
            "class_name": "Light Vehicle",
            "is_default": true,
            "asset_variation_id": 7,
            "asset": {...}
        }
    ]
}

Get Inventory to Hero

curl -X GET "https://api.lootlocker.io/server/player/1234/heroes/5678/inventory"

This call allows you to get the inventory for a specific hero belonging to a player.

This call is paginated.

{
    "total": 1,
    "items": [
        {
            "instance_id": 4,
            "variation_id": null,
            "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/server/player/1234/heroes/5678/loadout"

Get a heros full loadout.

{
    "items": [
        {
            "variation_id": 370,
            "instance_id": 464,
            "mounted_at": "2021-02-24T09:37:42+00:00",
            "asset": {...},
            "rental": {
                "is_rental": false,
                "time_left": null,
                "duration": null,
                "is_active": null
            }
        }
    ]
}

Equip Asset for Hero Loadout

curl -X POST "https://api.lootlocker.io/server/player/1234/heroes/5678/loadout" \
    -H "LL-Version: 2021-03-01" \
    -H "Content-Type: application/json" \
    -H "x-auth-token: unR7YZAsf7aXxMP8BXj8fTP1fevarOmajhWabRuM" \
    -d "{\"instance_id\": 464}"

This endpoint will equip an asset instance to a hero. The response is a full representation of the hero's loadout.

In the case of Universal Assets, you can send the body as in the Universal Asset example on the right. Rental assets also work with rental_option_id instead of asset_variation_id.

curl -X POST "https://api.lootlocker.io/server/player/1234/heroes/5678/loadout" \
    -H "LL-Version: 2021-03-01" \
    -H "Content-Type: application/json" \
    -H "x-auth-token: unR7YZAsf7aXxMP8BXj8fTP1fevarOmajhWabRuM" \
    -d "{\"asset_id\": 464, \"asset_variation_id\": 5817}"

{
    "items": [
        {
            "variation_id": 370,
            "instance_id": 464,
            "mounted_at": "2021-02-24T09:37:42+00:00",
            "asset": {...},
            "rental": {
                "is_rental": false,
                "time_left": null,
                "duration": null,
                "is_active": null
            }
        }
    ]
}

Unequip Asset for Hero Loadout

curl -X DELETE "https://api.lootlocker.io/server/player/1234/heroes/5678/loadout/464" \
    -H "LL-Version: 2021-03-01" \
    -H "Content-Type: application/json" \
    -H "x-auth-token: unR7YZAsf7aXxMP8BXj8fTP1fevarOmajhWabRuM"

This endpoint will unequip an asset instance to a hero. The response is a full representation of the heros loadout.

{
    "items": [
        {
            "variation_id": 370,
            "instance_id": 465,
            "mounted_at": "2021-03-01T19:08:31+00:00",
            "asset": {...},
            "rental": {
                "is_rental": false,
                "time_left": null,
                "duration": null,
                "is_active": null
            }
        }
    ]
}

Leaderboards

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. Becuase 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 eachother 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 must use player_id, but when retrieving data LootLocker will automatically attach player data such as name and other public data on that player.

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.

Create Leaderboard

curl -X POST "https://api.lootlocker.io/server/leaderboards" \
-d "{\"name\": \"Global Leaderboard\", \"key\": \"some_key\", \"direction_method\": \"descending\", \"enable_game_api_writes\": false, \"overwrite_score_on_submit\": false, \"has_metadata\": true, \"type\": \"generic\"}" \
-H "Content-Type: application/json"

{
  "id": 3,
  "key": "some_key",
  "created_at": "2021-03-16T09:08:46.387539986Z",
  "updated_at": "2021-03-16T09:08:46.387539986Z",
  "direction_method": "descending",
  "enable_game_api_writes": false,
  "overwrite_score_on_submit": false,
  "has_metadata": true,
  "game_id": 100,
  "name": "Global Leaderboard",
  "type": "generic"
}

Create a new leaderboard new leaderboard.

Available Input Fields

All fields are required.

Field	Description
name	Name of your leaderboard, used primarily in admin
key	Optional unique key, can be used to retrieve the leaderboard later
type	player/generic depending on your use case
direction_method	Can only be ascending/descending, based on whether higher rank is lowest or highest number
enable_game_api_writes	Enable Game API to submit scores
overwrite_score_on_submit	Submitting a new score for member will always overwrite their existing score on leaderboard
has_metadata	Enable submitting metadata along side the score for more data on each entry. Not possible to change later.

Update Leaderboard

curl -X PUT "https://api.lootlocker.io/server/leaderboards/1" \
-d "{\"name\": \"Global Leaderboard 2\", \"key\": \"some_key\", \"direction_method\": \"ascending\", \"enable_game_api_writes\": true, \"overwrite_score_on_submit\": true}" \
-H "Content-Type: application/json"

{
  "id": 3,
  "key": "some_key",
  "created_at": "2021-03-16T09:08:46.387539986Z",
  "updated_at": "2021-03-16T09:11:32.031258686Z",
  "direction_method": "ascending",
  "enable_game_api_writes": true,
  "overwrite_score_on_submit": true,
  "has_metadata": true,
  "game_id": 100,
  "name": "Global Leaderboard 2",
  "type": "generic"
}

URL Structure

/server/leaderboards/<leaderboard_id|leaderboard_key>

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
name	Name of your leaderboard, used primarily in admin
key	Optional unique key, can be used to retrieve the leaderboard later
type	player/generic depending on your use case
direction_method	Can only be ascending/descending, based on whether higher rank is lowest or highest number
enable_game_api_writes	Enable Game API to submit scores
overwrite_score_on_submit	Submitting a new score for member will always overwrite their existing score on leaderboard

Delete Leaderboard

curl -X DELETE "https://api.lootlocker.io/server/leaderboards/1"

Versions after 2021-06-01 will return a 204 status code with no response body

Versions prior to 2021-06-01:

{
  "id": 3,
  "key": "some_key",
  "created_at": "2021-03-16T09:08:46.387539986Z",
  "updated_at": "2021-03-16T09:11:32.031258686Z",
  "direction_method": "ascending",
  "enable_game_api_writes": true,
  "overwrite_score_on_submit": true,
  "game_id": 100,
  "name": "Global Leaderboard 2",
  "type": "generic"
}

Soft delete a leaderboard. It will no longer be possible to submit scores to that leaderboard.

URL Structure

/server/leaderboards/<leaderboard_id|leaderboard_key>

URL Parts

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

Submit Score

curl -X POST "https://api.lootlocker.io/server/leaderboards/1/submit" \
-d "{\"member_id\": \"test_id\", \"score\": 1000, \"metadata\": \"some metadata\"}" \
-H "Content-Type: application/json"

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

URL Structure

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

URL Parts

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

Submit scores for member on leaderboard.

Get All Member Ranks

curl -X GET "https://api.lootlocker.io/server/leaderboards/member/4?count=1

{
  "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
  }
}

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.

URL Structure

/server/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/server/leaderboards/1/list?count=10"

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.

{
  "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

/server/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

Drop Tables

Compute and Lock Drop Table

curl -X POST "https://api.lootlocker.io/server/player/1/droptables/2/compute" \
    -H "LL-Version: 2021-03-01" \
    -H "x-auth-token: f31aq540cb18e5ca0ee911c8284de5b5b93d6a01"

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 on your server, 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 caluclation. The tag is included by adding it as a GET style parameter: ?tag=skeleton.

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

The ID's in the URL is the player_id and 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/server/player/1/droptables/2/pick" \
    -H "LL-Version: 2021-03-01" \
    -H "x-auth-token: f31aq540cb18e5ca0ee911c8284de5b5b93d6a01" \
    -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 Get Assets To Game for the full structure.

Note that a limit can be imposed on the number of drops that can be picked by the player. This number can be obtained from the Asset List, or any inventory call under the asset property, in the field called drop_table_max_picks. If the value is null or 0 it means there is no limit.

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

Triggers

Invoke Trigger on Behalf of Player

curl -X POST "https://api.lootlocker.io/server/trigger" \
    -H "LL-Version: 2021-03-01" \
    -H "Content-Type: application/json" \
    -H "x-auth-token: fh2ubeotOwpJOyNLSMw14f6OLqavFJK2Ts3Ev889" \
    -d "{\"name\": \"my.trigger\", \"player_id\": 1234}

This endpoint lets you invoke a trigger on behalf of a player.

{
    "xp": {
        "previous": 0,
        "current": 0
    },
    "levels": [
        {
            "level": 0,
            "is_prestige": false,
            "xp_threshold": 0
        },
        {
            "level": 1,
            "is_prestige": false,
            "xp_threshold": 1000
        }
    ],
    "granted_assets": [
        {...}
    ]
}

Purchases

Check Status of Player Purchase By ID

curl -X GET "https://api.lootlocker.io/server/player/1/purhcase/2" \
    -H "LL-Version: 2021-03-01" \
    -H "x-auth-token: unR7YZAsf7aXxMP8BXj8fTP1fevarOmajhWabRuM"

This endpoint will let you verify that a purchase by a player has the status the game client reports, as well as list the products included in the purchase.

The following order_status can currently be returned:

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

Status	Final	Description
open	No	The order is being processed
succeeded	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

If an order is not yet Final, you should not take any action on it as the status is likely to change in the near future.

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.

Check Status of Player Purchase By Platform Transaction ID

curl -X GET "https://api.lootlocker.io/server/player/1/purhcase/transaction/1000000673097863" \
    -H "LL-Version: 2021-03-01" \
    -H "x-auth-token: unR7YZAsf7aXxMP8BXj8fTP1fevarOmajhWabRuM"

This endpoint is identical to the one for checking by ID, except that it uses the First Party Platform Transaction ID to look up the data. The response is also identical.

The no_products flag from the other call also works here.