This article is a work in progress.

Please help expand and improve it. The talk page may contain suggestions.
Note: Document the create world endpoint

The now-defunct Blockheads Cloud used an HTTP API for communication between the client and server. This page documents its endpoints.

Authentication

The API uses a very insecure method of "authentication", which is detailed below.

Challenge

All cloud sessions start with the client making a POST request to the https://cloud.theblockheads.net/api/challenge endpoint, containing the following URL-encoded fields:

The server responds with a JSON object containing the following properties:

status: Must be ok for a successful request. badVersion indicates that the client version is not supported. The client will show a generic error for any other value.
baseUrl: The base URL to be used for future API requests.
authToken: An arbitrary string chosen by the server. The client will use it in the method described below.

The client will now make a POST request to ${baseUrl}/authenticate containing the following URL-encoded fields:

appVersion: The version of the Blockheads client.
authKey: The client encodes this as follows:
- Take the static string -AcwL&jt#qWhq%dlo^xRAaTlCkQt$kgl
- Append the user's iCloud account ID (TODO: what value is used on android?)
- Append the authToken from the challenge response
- Hash to MD5
crystals: The amount of time crystals the user has (integer).
dId: The user's device ID
forceBeta: Unknown what exactly this means, but the client seems to always send true
icId: The user's iCloud ID
platform: Can be iOS or Android/Google Play. The game was on the Amazon app store at one point so there could be a value for that too.

The server responds with a JSON object containing the following properties:

status: Must be ok for a successful request. banned indicates that the user is cloud-banned. The client will show a generic error for any other value.
sId: The session ID. Arbitrary and server-chosen
spId: The user's support ID. Arbitrary and server-chosen; the official cloud used a 6-character alphabetic string. The client does not enforce this.

The same endpoint is used for both searching and the Random World button.

The client sends a POST request to ${baseUrl}/world/search with the following fields:

sId: The session ID from the authentication response
name: The string to search for in the world name. If omitted, the client is requesting a random world.
pvp: If specified, only return worlds with PVP enabled (true) or disabled (false)
custom: If specified, only return worlds with custom rules enabled (true) or disabled (false)
expert: If specified, only return worlds with expert mode enabled (true) or disabled (false)
wIds (array): Request specific worlds by ID. Cannot be used with any of the other options except sId. This is used to update information about worlds in the client's cache.

The server responds with a JSON object containing the following properties:

status: Must be ok for a successful request.
worlds: JSON array, containing an object for each world returned with the following fields:
- wIdThe world ID. The client does not care if this is a string or integer.
- name: The name of the world
- players: The number of players currently connected to the world

The client sends a POST request to ${baseUrl}/world/connect with the following fields:

The server responds with a JSON object containing the following properties:

status: Must be ok for a successful request. Other values:
- badName: The nickname is already taken
- illegalName: Nickname too long or contains illegal characters
- bannedName: Nickname is banned (Unknown when or why this would ever be used)
- unavailable: World is unavailable due to server error
- maintenance: World is unavailable due to server maintenance
- noTime: World has no credit
- startup The server must be started. The client waits 2 seconds and tries again.
ip: The IP address of the server hosting the world
port: The port the world is hosted on
key: The key for the client to use when connecting to the world. Used to validate that the user is authenticated to their nickname. Generated as follows:
- Take the string given to the server binary in the --cloud_salt parameter
- Append the user's alias
- Hash to MD5