Vintage Story

In-Game Vintage Story server lister

Vintage Story

Vintage Story is a voxel-based wilderness survival game written in the C# programming language.

Table of contents

HTTP API endpoints

Function	Method	Endpoint URL
Register server	POST	https://masterserver.vintagestory.at/api/v1/servers/register
Server heartbeat	POST	https://masterserver.vintagestory.at/api/v1/servers/heartbeat
View server list	GET	https://masterserver.vintagestory.at/api/v1/servers/list
View latest stable game version	GET	https://api.vintagestory.at/lateststable.txt
Get a player's UID	POST	https://auth3.vintagestory.at/resolveplayername
Get a player's name	POST	https://auth2.vintagestory.at/resolveplayeruid

Server listing protocol

For a server to get listed, all Vintage Story servers need to first register on the server list and then periodically send a heartbeat HTTP request. Clients will then retrieve the server list. This all happens through HTTP endpoints. A re-implementation of the masterserver made in Python is available on GitHub:

https://github.com/CDWimmer/VintageStoryMasterServer

(HTTP POST) Register server

Endpoint: https://masterserver.vintagestory.at/api/v1/servers/register

Sample JSON payload:

{
    "port":42424,
    "name":"My cool vintage story server",
    "icon":"",
    "playstyle":{
        "id":"surviveandbuild",
        "langCode":"preset-surviveandbuild"
    },
    "maxPlayers":48,
    "gameVersion":"1.20.3",
    "hasPassword":false,
    "Mods":[
        {
            "id":"signs",
            "version":"1.0.2"
        },
        [ ... ]
    ],
    "serverUrl":"https://lolcat.ca",
    "gameDescription":"Some description here",
    "whitelisted":true
}

The gameDescription attribute can contain basic HTML markup like <h1> tags and links.
Sample successful response:

{
    "data": "server-token-here",
    "status": "ok"
}

The server token consists of 32 random bytes encoded as base64.
Sample bad response from the server:

{
    "status": "bad",
    "data": "port not opened"
}

If you have any deduction skills, you will see that in order to get listed, you need to host a Vintage Story server on the same host the request is originating from before attempting to create a list entry.

(HTTP POST) Server heartbeat

https://masterserver.vintagestory.at/api/v1/servers/heartbeat

Sample JSON payload:

{
    "token": "your-token-here",
    "players": 500
}

Sample successful response:

{
    "status": "ok"
}

Sample bad response from the server:

{
    "status": "timeout",
    "data": "timeout"
}

When the masterserver replies with a timeout response, the Vintage Story server should re-register their server.

(HTTP GET) View server list

https://masterserver.vintagestory.at/api/v1/servers/list

Sample JSON response:

{
    "status": "ok",
    "data": {
        [
            "serverName": "Vintage Story Server",
            "serverIP": "1.1.1.1:25209",
            "playstyle": {
                "id": "surviveandbuild",
                "langCode": "preset-surviveandbuild"
            },
            "mods": {
                [
                    "id": "primitivesurvival",
                    "version": "3.7.5"
                ],
                [ ... ]
            }
            "maxPlayers": "16",
            "players": 10,
            "gameVersion": "1.20.1",
            "hasPassword": false,
            "whitelisted": true,
            "gameDescription": "Some description here"
        ],
        [ ... ]
    }
}

(HTTP GET) View latest version

Endpoint: https://api.vintagestory.at/lateststable.txt

This endpoint simply returns the game version in text form.

Get player information

Vintage Story has limited, obscure and undocumented API endpoints available to get player information. Make sure to set the Content-Type: application/x-www-form-urlencoded header to all POST requests, otherwise it will fail. The valid attribute seems to always return 1. If an error occurs, the playername or playeruid field should be empty.

(HTTP POST) Get a player's UID

Endpoint: https://auth3.vintagestory.at/resolveplayername

Sample url-encoded payload to send:

playername=lolcat

Sample response:

{
    "playeruid": "HoTGuCSFEkJtltbThBSmzKy2",
    "valid": 1
}

(HTTP POST) Get a player's name by UID

Endpoint: https://auth2.vintagestory.at/resolveplayeruid

Sample url-encoded payload to send:

uid=UOykyPSlZsMvjEjZZa%2B7409L

Sample response:

{
    "playername": "Tyron",
    "valid": 1
}