API Documentation


The Black Forest API was written to be easy and versatile. Therefore, while it uses some concepts of REST, it is not a pure REST API.

All API interactions are done over HTTP. Like in REST, every URL specifies one resource or action and parameters serve to provide details or filters.

The API does not care how you submit parameters. You can GET, POST use cookies or headers. You can also mix them. This is especially important for authentication, which you never want to send as GET parameters, so for GET requests, use headers.

All API responses are in JSON format and contain nested data. The individual elements within the JSON follow no specific order, but every object has a unique ID (unique within that object class, so while there will only ever be one peasant with the ID #5, there can also be a village with the ID #5). So, for example, family overview data set can look like this:

		    "id": 1,
		    "name": "Becker",
		    "number_peasants": 4,
		    "number_plots": 16,
		    "village": {
		        "name": "Feuerau",
		        "day": 0,
		        "id": 2
Where the family object includes the village object that the family belongs to.
Depending on the request, various levels of details will be exposed, so not all properties of an object are always present.

You can find a call-by-call specification on the API specification page.


Most of the API requires a client to authenticate. This is done using the two parameters

This is a simple number giving a unique ID to every player account.
This is a long, randomly generated alphanumeric string that you receive after account confirmation and need to store safely in the client.
These parameters need to be provided with almost every request, so your client should simply always send them.

Joining Games

To join a game, your client first needs to retrieve a list of available games, then for the game the player chooses to join, retrieve the list of available families, and then submit one family choice:

This gets a list of villages that can be joined (i.e. where the game is not yet running)
Get a list of families in the village {id} with basic information.
Take control of family {id} and join their village / game.

You can also call families/instant to trigger the "instant action" feature. The game will randomly select an NPC family, put it under your control, and return an array ('village_id' => {id}, 'family_id' => {id}) as result, which you can plug into further calls (e.g. to start that game, which the player would expect from "instant action").

Call Specifications

You can find a call-by-call specification on the API specification page.