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 Maintaining 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 receives. 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"
        }
    ]
}

Inspecting a LootBox

curl -X GET "https://api.lootlocjer.io/server/player/1234/asset/instances/57613/inspect"

Inspecting a lootbox can be done using this endpoint.

{
    "success": true,
    "contents": [
        {
            "asset_id": 298778,
            "asset_variation_id": null,
            "asset_rental_option_id": null,
            "weight": 1
        },
        {
            "asset_id": 298784,
            "asset_variation_id": 2,
            "asset_rental_option_id": null,
            "weight": 1
        }
    ]
}

Opening a LootBox

curl -X PUT "https://api.lootlocker.io/server/player/1234/asset/instances/57613/open"

This endpoint will open a lootbox and grant the rewards to the player.

{
    "success": true,
    "check_grant_notifications": true,
    "assets": [
        {
            "instance_id": 6,
            "variation_id": 2,
            "rental_option_id": null,
            "quantity": 1,
            "asset": {....}
        }
    ]
}

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/server/players/1/assets/instances/1/progressions?count=10&after=01GJN6J46DM00Z88WR225Y9P77"
-H "LL-Version: 2021-03-01" \
-H "x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab"

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

URL Structure

/server/players/<player_id>/assets/instances/<asset_instance_id>/progressions

{
  "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
player_id	ID of the player
asset_instance_id	ID 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 100 is allowed

Get Asset Instance Progression By Key

curl -X GET "https://api.lootlocker.io/server/players/1/assets/instances/1/progressions/summer_battle_pass"
-H "LL-Version: 2021-03-01" \
-H "x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab"

Get a single asset instance progression by Key.

URL Structure

/server/players/<player_id>/assets/instances/<asset_instance_id>/progressions/<progression_key>

{
  "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
player_id	ID of the player
asset_instance_id	ID the asset instance
progression_key	Key of the progression

Add points to an asset instance progression

curl -X POST "https://api.lootlocker.io/server/players/1/assets/instances/1/progressions/summer_battle_pass/points/add" \
-H "LL-Version: 2021-03-01" \
-H "x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab" \
-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 the asset instance leveled up, awarded_tiers fields will contain acquired rewards.

URL Structure

/server/players/<player_id>/assets/instances/<asset_instance_id>/progressions/<progression_key>/points/add

{
  "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
player_id	ID of the player
asset_instance_id	ID the asset instance
progression_key	Key of the progression

Available input fields

amount is required.

Field	Description
amount	Amount of points to be add.

Subtract points from an asset instance progression

curl -X POST "https://api.lootlocker.io/server/players/1/assets/instances/1/progressions/spring_battle_pass/points/subtract" \
-H "LL-Version: 2021-03-01" \
-H "x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab" \
-H "Content-Type: application/json" \
-d "{\"amount\": 10 }"

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

/server/players/<player_id>/assets/instances/<asset_instance_id>/progressions/<progression_key>/points/subtract

{
    "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
player_id	ID of the player
asset_instance_id	ID the asset instance
progression_key	Key of the progression

Available input fields

amount is required.

Field	Description
amount	Amount of points to subtract.

Reset an asset instance progression

curl -X POST "https://api.lootlocker.io/server/players/1/assets/instances/1/progressions/spring_battle_pass/reset" \
-H "LL-Version: 2021-03-01" \
-H "x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab"

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

URL Structure

/server/players/<player_id>/assets/instances/<asset_instance_id>/progressions/<progression_key>/reset

{
    "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
player_id	ID of the player
asset_instance_id	ID the asset instance
progression_key	Key of the progression

Delete an asset instance progression

curl -X DELETE "https://api.lootlocker.io/server/players/1/assets/instances/1/progressions/spring_battle_pass" \
-H "LL-Version: 2021-03-01" \
-H "x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab"

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

URL Structure

/server/players/<player_id>/assets/instances/<asset_instance_id>/progressions/<progression_key>

URL Parts

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

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/server/progressions?count=10&after=01GJ34JX0VKJKM4P6X9JHZ8FDF"
-H "LL-Version: 2021-03-01" \
-H "x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab"

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

URL Structure

/server/progressions

{
  "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 100 is allowed

Get Progression By Key

curl -X GET "https://api.lootlocker.io/server/progressions/fighter"
-H "LL-Version: 2021-03-01" \
-H "x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab"

Get a single progression by key.

URL Structure

/server/progressions/<progression_key>

{
  "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/server/progressions/fighter/tiers/2"
-H "LL-Version: 2021-03-01" \
-H "x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab"

Gets a single progression tier with rewards.

URL Structure

/server/progressions/<progression_key>/tiers/<progression_step>

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

curl -X GET "https://api.lootlocker.io/server/progressions/fighter/tiers?count=10&after=1"
-H "LL-Version: 2021-03-01" \
-H "x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab"

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

/server/progressions/<progression_key>/tiers

{
  "pagination": {
    "next_cursor": null,
    "previous_cursor": null,
    "total": 5
  },
  "items": [
    {
      "step": 1,
      "points_threshold": 0,
      "rewards": {
        "progression_points_rewards": [],
        "progression_reset_rewards": [],
        "asset_rewards": [],
        "currency_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 100 is allowed

Player

Get Player Info By Game Session Tokens

Allows retrieving player information by game session tokens.

curl --location --request POST 'https://api.lootlocker.io/server/player/info/token' \
--header 'x-auth-token: <YOUR AUTH TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "tokens": [
        "0e077f4a96ef299faea8a8762edc15f511af5686",
        "69df5e862256564cd42d1efa0abcd7b5751ef857",
        "774c6db632cce86b1d2dd864428133caf3271e9c",
        "357dea0afe834b4903e764abd899015b8831ce56",
        "f5a84368936b96c23ac2bb59190c27096f98a5d5"
    ]
}'

URL Structure

/server/player/info/token

{
    "failed_tokens": [
        "0e077l1a96ef299fbla8a8762edc15f511af5699"
    ],
    "player_info_list": [
        {
            "id": "01J55SK5RJ5H25D1X5MM8A0CBQ",
            "legacy_id": 2,
            "token": "0e077f4a96ef299faea8a8762edc15f511af5686"
        },
        {
            "id": "01J55SQQJS74088GW2SBEBPPT1",
            "legacy_id": 3,
            "token": "69df5e862256564cd42d1efa0abcd7b5751ef857"
        },
        {
            "id": "01J55SR4SZAC1YFER8K6QTQ9M0",
            "legacy_id": 4,
            "token": "774c6db632cce86b1d2dd864428133caf3271e9c"
        },
        {
            "id": "01J55SREP9MMQ8P558Z0MRM07D",
            "legacy_id": 5,
            "token": "357dea0afe834b4903e764abd899015b8831ce56"
        },
        {
            "id": "01J55SS1PG3AP1J9N071E575XJ",
            "legacy_id": 6,
            "token": "f5a84368936b96c23ac2bb59190c27096f98a5d5"
        }
    ]
}

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",
      "ulid": "01H00MTAPTE4VRPRZJZMT5RTBH"
    },
    {
      "player_id": 2,
      "player_public_uid": "4FDGF738",
      "name": "Player 2 Name",
      "last_active_platform": "xbox_one",
      "ulid": "01H00MTAPTE4VRPRZJZMT5RTBH"
    },
    {
      "player_id": 3,
      "player_public_uid": "JARL7PGR",
      "name": "Player 3 Name",
      "last_active_platform": "guest",
      "ulid": "01H00MTAPTE4VRPRZJZMT5RTBH"
    },
    {
      "player_id": 4,
      "player_public_uid": "9HDK4F5Y",
      "name": "Player 4 PSN Name",
      "last_active_platform": "psn",
      "platform_player_id": "1234567890",
      "ulid": "01H00MTAPTE4VRPRZJZMT5RTBH"
    },
    {
      "player_id": 5,
      "player_public_uid": "3XTMHFS3",
      "name": "Player 5 Steam Name",
      "last_active_platform": "steam",
      "platform_player_id": "9465748036854778475",
      "ulid": "01H00MTAPTE4VRPRZJZMT5RTBH"
    },
    {
      "player_id": 6,
      "player_public_uid": "9RKPSRRT",
      "name": "Player 6 XBox Name",
      "last_active_platform": "xbox_one",
      "platform_player_id": "E51D19530BBE721286F75C03B934E5EB7CA23B99",
      "ulid": "01H00MTAPTE4VRPRZJZMT5RTBH"
    },
    {
      "player_id": 7,
      "player_public_uid": "T4HV7G5D",
      "name": "Player 7 GuestLogin Name",
      "last_active_platform": "guest",
      "platform_player_id": "a270686a-7dd7-482f-89b6-9b2a634f46fb",
      "ulid": "01H00MTAPTE4VRPRZJZMT5RTBH"
    }
  ]
}

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": []
        }
    ]
}

Get Multiple Players Public Persistent Storage Values

curl -X POST "https://api.lootlocker.io/server/players/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.

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

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,
            "revision_id": "01GPNZHCVEF6F0QGA3V2B7CN44",
            "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,
    "revision_id": "01GPNZHCVEF6F0QGA3V2B7CN44",
    "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,
    "revision_id": "01GPNZHCVEF6F0QGA3V2B7CN44",
    "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"
}

The following fields can be included to set the file's properties (all strings):

Field	Description
`purpose`	The purpose of the file. Defaults to `PLAYER_FILE` if not provided.
`is_public`	Whether the file should be public or not. Defaults to `false` if not provided.

Update a File

curl -X PUT 'https://api.lootlocker.io/server/players/{player_id}/files/{file_id}' \
  -H 'x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab' \
  -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.

{
  "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 following fields can be included to set the file's properties (all strings):

Field	Description
`purpose`	The purpose of the file. Defaults to `PLAYER_FILE` if not provided.
`is_public`	Whether the file should be public or not. Defaults to `false` if not provided.

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/server/players/1/progressions?count=10&after=01GJN6J46DM00Z88WR225Y9P77"
-H "LL-Version: 2021-03-01" \
-H "x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab"

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

URL Structure

/server/players/<player_id>/progressions

{
  "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
player_id	ID of the player

Query Parameters:

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

Get Player Progression By Key

curl -X GET "https://api.lootlocker.io/server/players/1/progressions/fighter"
-H "LL-Version: 2021-03-01" \
-H "x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab"

Get a single player progression by Key.

URL Structure

/server/players/<player_id>/progressions/<progression_key>

{
  "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
player_id	ID of the player
progression_key	Key of the progression

Add points to a player progression

curl -X POST "https://api.lootlocker.io/server/players/1/progressions/fighter/points/add" \
-H "LL-Version: 2021-03-01" \
-H "x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab" \
-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

/server/players/<player_id>/progressions/<progression_key>/points/add

{
  "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
player_id	ID of the player
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/server/players/1/progressions/mage/points/subtract" \
-H "LL-Version: 2021-03-01" \
-H "x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab" \
-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

/server/players/<player_id>/progressions/<progression_key>/points/subtract

{
    "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
player_id	ID of the player
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/server/players/1/progressions/mage/reset" \
-H "LL-Version: 2021-03-01" \
-H "x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab"

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

URL Structure

/server/players/<player_id>/progressions/<progression_key>/reset

{
    "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
player_id	ID of the player
progression_key	Key of the progression

Delete a player progression

curl -X DELETE "https://api.lootlocker.io/server/players/1/progressions/mage" \
-H "LL-Version: 2021-03-01" \
-H "x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab"

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

URL Structure

/server/players/<player_id>/progressions/<progression_key>

URL Parts

Part	Description
player_id	ID of the player
progression_key	Key of the progression

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 underlying 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 heroes 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 heroes 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
            }
        }
    ]
}

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/server/players/1/characters/1/progressions?count=10&after=01GJN6J46DM00Z88WR225Y9P77"
-H "LL-Version: 2021-03-01" \
-H "x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab"

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

URL Structure

/server/players/<player_id>/characters/<character_id>/progressions

{
  "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
player_id	ID of the player
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 100 is allowed

Get Character Progression By Key

curl -X GET "https://api.lootlocker.io/server/players/1/characters/1/progressions/fighter"
-H "LL-Version: 2021-03-01" \
-H "x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab"

Get a single character progression by Key.

URL Structure

/server/players/<player_id>/characters/<character_id>/progressions/<progression_key>

{
  "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
player_id	ID of the player
character_id	ID of the character
progression_key	Key of the progression

Add points to a character progression

curl -X POST "https://api.lootlocker.io/server/players/1/characters/1/progressions/fighter/points/add" \
-H "LL-Version: 2021-03-01" \
-H "x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab" \
-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

/server/players/<player_id>/characters/<character_id>/progressions/<progression_key>/points/add

{
  "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
player_id	ID of the player
character_id	ID of the character
progression_key	Key of the progression

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/server/players/1/characters/1/progressions/mage/points/subtract" \
-H "LL-Version: 2021-03-01" \
-H "x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab" \
-H "Content-Type: application/json" \
-d "{\"amount\": 10 }"

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

/server/players/<player_id>/characters/<character_id>/progressions/<progression_key>/points/subtract

{
    "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
player_id	ID of the player
character_id	ID of the character
progression_key	Key of the progression

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/server/players/1/characters/1/progressions/mage/reset" \
-H "LL-Version: 2021-03-01" \
-H "x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab"

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

URL Structure

/server/players/<player_id>/characters/<character_id>/progressions/<progression_key>/reset

{
    "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
player_id	ID of the player
character_id	ID of the character
progression_key	Key of the progression

Delete a character progression

curl -X DELETE "https://api.lootlocker.io/server/players/1/characters/1/progressions/mage" \
-H "LL-Version: 2021-03-01" \
-H "x-auth-token: 5995a0ce1afe87ac9dd49c509bd2fcae6f7d79ab"

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

URL Structure

/server/players/<player_id>/characters/<character_id>/progressions/<progression_key>

URL Parts

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

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. 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 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

Leaderboard Schedules & Rewards

These endpoints let you manage leaderboard schedules through the Server API.

Schedules

Cron Expressions You can use cron expressions to define your schedule. These expressions follow the traditional cron spec.

A great tool to familiarise yourself with it is crontab guru.

Additionally, we do support non-standard descriptors as follows:

@daily: everyday, at midnight UTC.

@weekly: on Sunday, at midnight UTC.

@monthly on the first day of the month, at midnight UTC.

Create

curl --request POST 'https://api.lootlocker.io/server/leaderboards/10/schedule' \
--header 'x-auth-token: <YOUR AUTH TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "cron_expression": "@daily"
}'

URL Structure

POST /server/leaderboards/{leaderboard_id}/schedule

{
  "next_run": "2024-02-25T04:05:00Z",
  "schedule": [
    "2024-02-25T04:05:00Z",
    "2024-03-03T04:05:00Z",
    "2024-03-10T04:05:00Z",
    "2024-03-17T04:05:00Z",
    "2024-03-24T04:05:00Z"
  ]
}

Get

curl --request GET 'https://api.lootlocker.io/server/leaderboards/10/schedule' \
--header 'x-auth-token: <YOUR AUTH TOKEN>' \

URL Structure

GET /server/leaderboards/{leaderboard_id}/schedule

{
    "cron_expression": "@daily",
    "last_run": null,
    "next_run": "2024-08-26T22:00:00Z",
    "schedule": [
        "2024-08-26T22:00:00Z",
        "2024-08-27T00:00:00Z",
        "2024-08-28T00:00:00Z",
        "2024-08-29T00:00:00Z",
        "2024-08-30T00:00:00Z"
    ]
}

Delete

curl --request DELETE 'https://api.lootlocker.io/server/leaderboards/10/schedule' \
--header 'x-auth-token: <YOUR AUTH TOKEN>' \

URL Structure

DELETE /server/leaderboards/{leaderboard_id}/schedule

HTTP Status Code 204 No Content.

Rewards

Attach rewards to be granted to players on leaderboard resets based on configured predicates.

Create

curl --request POST 'https://api.lootlocker.io/server/leaderboards/10/reward' \
--header 'x-auth-token: <YOUR AUTH TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "reward_id": "01HM6G77Y6B2Y4CGSW8PHPSGQ0",
  "reward_kind": "asset",
  "predicates": [
    {
      "type": "between",
      "args": {
        "min": 1,
        "max": 10,
        "method": "by_rank",
        "direction": "asc"
      }
    }
  ]
}'

URL Structure

POST /server/leaderboards/{leaderboard_id}/reward

HTTP Status Code 204 No Content.

Delete

curl --request DELETE 'https://api.lootlocker.io/server/leaderboards/10/reward/01J2BGMKBZYQDJS5N1FJWDJFB2' \
--header 'x-auth-token: <YOUR AUTH TOKEN>' \

URL Structure

DELETE /server/leaderboards/{leaderboard_id}/reward/{reward_id}

HTTP Status Code 204 No Content.

Download

curl --request GET 'https://api.lootlocker.io/server/leaderboards/archive/2/7916/2024/08/JSON/file.txt/download' \
--header 'x-auth-token: <YOUR_AUTH_TOKEN>' \

URL Structure

GET /server/leaderboards/archives/{key}/download

HTTP Status Code 200 OK + the file downloaded.

List

curl --request GET 'https://api.lootlocker.io/server/leaderboards/10/archive' \
--header 'x-auth-token: <YOUR_AUTH_TOKEN>' \

URL Structure

GET /server/leaderboards/{leaderboard_id}/archive

{
  "objects": [
    {
      "last_modified": "2024-05-28T15:48:05Z",
      "content_type": "application/json",
      "key": "my-key",
      "content_length": 200
    }
  ]
}

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 calculation. 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": [
        {...}
    ]
}

Balances

Get Wallet

curl --location 'https://api.lootlocker.io/server/wallet/{wallet_id}' \
--header 'x-auth-token: {x-auth-token}'

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

HTTP Request

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

Get Wallet For Holder

curl --location 'https://api.lootlocker.io/server/wallet/holder/{holder_id}' \
--header 'x-auth-token: {x-auth-token}'

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

HTTP Request

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

Parameters

Parameter	Type	Description
holder_id	string	The holder id of the wallet

List Balances

curl --location 'https://api.lootlocker.io/server/balances/wallet/{wallet_id}' \
--header 'x-auth-token: {x-auth-token}'

{
    "balances": [
        {
            "created_at": "2023-05-10T09:27:00Z",
            "amount": "4184768942",
            "holder_type": "player",
            "currency": {
                "code": "woo",
                "name": "Wood",
                "id": "01H00MTAPTE4VRPRZJZMT5RTBH"
            },
            "holder_id": 2422917
        }
    ]
}

HTTP Request

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

Parameters

Parameter	Type	Description
wallet_id	string	The id of the wallet

Create New Wallet

curl --location 'https://api.lootlocker.io/server/wallet' \
--header 'x-auth-token: {x-auth-token}' \
--header 'Content-Type: application/json' \
--data '{
    "holder_id": "01HAPV9QKKNV670X0QS932WESH",
    "holder_type": "player"
}'

{
    "wallet_id": "01HBGDG2NBDEFYXT8Q03M80RV3"
}

HTTP Request

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

Parameters

Parameter	Type	Description
holder_id	string	The holder id of the wallet
holder_type	string	The holder type of the wallet

Credit Balance

curl --location 'https://api.lootlocker.io/server/balances/credit' \
--header 'x-auth-token: {x-auth-token}' \
--header 'Content-Type: application/json' \
--data '{
    "amount": "1",
    "wallet_id": "01HAPKW6M4G8G6B43GY2K7BQHS",
    "currency_id": "01HAM2X360PD565H51JA8717JZ"
}'

{
    "balance": {
        "amount": "199976",
        "created_at": "2023-05-09T16:17:14Z",
        "currency_id": "01H00MTAPTE4VRPRZJZMT5RTBH",
        "holder_id": 123,
        "holder_type": "player"
    }
}

HTTP Request

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

Parameters

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

Debit Balance

curl --location 'https://api.lootlocker.io/server/balances/debit' \
--header 'x-auth-token: {x-auth-token}' \
--data '{
    "amount": "100",
    "holder_type": "player",
    "holder_id": 4885615,
    "currency_id": "01HAM2X360PD565H51JA8717JZ"
}'

{
    "balance": {
        "amount": "4184768942",
        "created_at": "2023-05-10T09:27:00Z",
        "currency_id": "01H00MTAPTE4VRPRZJZMT5RTBH",
        "holder_id": 2422917,
        "holder_type": "player"
    }
}

HTTP Request

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

Parameters

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

Currency

List Currencies

curl --location 'https://api.lootlocker.io/server/currencies/' \
--header 'x-auth-token {x-auth-token};

{
    "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/server/currencies/

🕸️ DEPRECATED: 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.