Create/Update Record

post
Create/update record

https://leaderboard-example.lvis.io/base_url/records
Request
Response
Request
Path Parameters
base_url
required
string
Base leaderboard URL for write endpoint. See Overview section for details.
Body Parameters
level
optional
string
Name or ID for project specific achievement level, e.g. “Rookie”, up to 50 characters.
public_data
optional
string
Arbitrary public data up to 15000 characters (usually serialised JSON string).
private_data
optional
string
Arbitrary private data up to 15000 characters (usually serialised JSON string).
public_id
optional
string
Public record identifier, up to 128 "A-Za-z0-9_-" characters.
name
optional
string
User name, arbitrary string up to 50 characters.
score
optional
integer
Numerical score (positive, negative or zero). Max: 9007199254740992. Min: -9007199254740992.
private_id
optional
string
Private unique record identifier, up to 128 "A-Za-z0-9_-" characters record identifier.
Response
201: Created
{
"private_id": "fb5a9c18-0745-48c4-b490-e036f1c94970"
}
404: Not Found
{
"error": "error text"
}

All and any of the values can be null or omitted in which case they are ignored.

Example

curl --request POST \
--url https://leaderboard-example.lvis.io/api/projects/edc619ed-32f3-4dcc-a2e6-1d213fbaf6a0/leaderboards/season/records \
--header 'Authorization: Bearer JmsmU5gZb6xNVUgQGoKcQLvQjRhKAUSb' \
--header 'Content-Type: application/vnd.api+json' \
--data '{
"public_id": "user_8163",
"score": 16538,
"name": "John Doe",
"level": "Rookie",
"public_data": "{\"avatar_url\":\"//example.com/avatar.jpg\"}",
"private_data": "{\"private_access_key\":\"Idq8gf886djh8918\"}"
}'

Records without score

If the score is missing or is null, then the record is not ranked in any way and is not returned in ranking requests, such as "Fetch top N players" or "Fetch total ranked players", but it is still possible to access this record by public_id or private_id.

Private and Public IDs truncation

If private_id or public_id is longer than allowed, it will be silently truncated to maximum allowed length.

Missing private_id

If private_id is omitted, a new is record created and private_id is generated by the system (random UUID). If private_id is present and record with this ID does not exist yet then a new record is created with given private_id. If private_id is present and the record exists it is updated with new data.

Public ID uniqueness

Public ID is not required to be unique across leaderboard records. In case if a non-unique public ID is used in "GET /ranks/public" query, the first record posted with the requested public ID is returned.

Private and public data size limit

A request is ignored if either private or public data exceed size limit.