For a more in-depth discussion of how to use the API, refer to the API Introduction.

Show/hide List Operations Expand Operations

Account Management

GET /account/

get account details

Documentation

Get the account details for your own account

Return

Parameter	Type	Versions	Description
200
id	integer	*
email	string	*	player/account e-mail address
name	string	*	player display name
registered	DateTime	*	when the account was registered
last_login	DateTime	*	when the account was last accessed (null if never)
karma[]	array of objects (Karma)	*	karma
karma[][id]	integer	*
karma[][type]	string	*	type or identifier string (one of 'gather', 'farm', 'build', )
achievements	array	*	which achievements we already have
families[]	array of objects (Family)	*	families controlled by this player
families[][id]	integer	*
families[][name]	string	*	family name
families[][ready]	boolean	*	ready for next turn (i.e. all actions set)?
families[][village]	object (Village)	*	village the family lives in
families[][village][id]	integer	*
families[][village][name]	string	*	village name
families[][village][pvp]	boolean	*	is PvP (attacking buildings) enabled?
families[][village][land]	boolean	*	start with ground or not (just hut) ?
families[][village][day]	integer	*	current day in the village
families[][village][season]	integer	*	current season (0 = summer, 1 = autum, 2 = winter)
families[][village][running]	boolean	*	is the game running? if not, day == 0 means it is not started, day > 0 means it is finished
families[][village][hours]	integer	*	how many hours until a turn is forced even if not all players issued orders
families[][wiped]	integer	*	on which day was the family wiped out? (null if they are still alive)
coins	integer	*	coins (silver coins - 12 silver = 1 gold)
score	integer	*	accumulated total score
games	integer	*	total number of games completed
highscore	integer	*	highest score in a single game
longest	integer	*	longest survival

POST /account/changemail

change your e-mail address

Name	Requirement	Type	Description
email		string	new e-mail address

POST /account/changename

change your username

Name	Requirement	Type	Description
username		string	new username

POST /account/forgotten

forgotten key reminder

Documentation

Forgotten key interface. Re-sends the old key for now.

This call does not require authentication.

Requirements

Name	Requirement	Type	Description
email	valid e-mail format	string	e-mail to remind of key

Return

Parameter	Type	Versions	Description
200
id	integer	*
email	string	*	player/account e-mail address
key	string	*	authentication key
confirmed	boolean	*	has the e-mail address been confirmed?

POST /account/register

create a new account

Documentation

Register account with a given e-mail address. Server will respond with temporary player data that includes an activation key.

This call does not require authentication.

Requirements

Name	Requirement	Type	Description
email	valid e-mail format	string	e-mail to register account for

Return

Parameter	Type	Versions	Description
200
id	integer	*
email	string	*	player/account e-mail address
key	string	*	authentication key
confirmed	boolean	*	has the e-mail address been confirmed?

POST /families/instant
- join random game
Documentation

Take control of a random NPC family and join their game. Returns an array village_id, family_id that can be used in further calls (e.g. opening that game)

POST /families/{family}/take

join game

Parameter	Type	Required?	Format	Description
password	string	true		password (only for private games)

Show/hide List Operations Expand Operations

Actions

POST /families/{family}/resources

set sleeping location for family

Name	Requirement	Type	Description
from	\d+	integer	building id of the source
to	\d+	integer	building id of the destination
what	\d+	string	which resource to move (wood, stone or food)
amount	\d+	integer	amount of the resource to move
family

POST /families/{family}/sethome/{home}

set sleeping location for family

POST /peasants/{peasant}/attack

attack building

Name	Requirement	Type	Description
peasant	\d+	integer	peasant id
x	\d+	integer	x coordinate of target plot
y	\d+	integer	y coordinate of target plot

POST /peasants/{peasant}/build/{what}

build

Name	Requirement	Type	Description
peasant	\d+	integer	peasant id
x	\d+	integer	x coordinate of target plot
y	\d+	integer	y coordinate of target plot
what		string	what to build

POST /peasants/{peasant}/clear

clear ruin

Name	Requirement	Type	Description
peasant	\d+	integer	peasant id
x	\d+	integer	x coordinate of target plot
y	\d+	integer	y coordinate of target plot

POST /peasants/{peasant}/foundation

lay a foundation

Name	Requirement	Type	Description
peasant	\d+	integer	peasant id
x	\d+	integer	x coordinate of target plot
y	\d+	integer	y coordinate of target plot

POST /peasants/{peasant}/gather/{what}

gather resources

Name	Requirement	Type	Description
peasant	\d+	integer	peasant id
what	(wood\|stone\|food\|deep)	string	name of the resource to gather

POST /peasants/{peasant}/harvest

harvest field

Name	Requirement	Type	Description
peasant	\d+	integer	peasant id
x	\d+	integer	x coordinate of target plot
y	\d+	integer	y coordinate of target plot

POST /peasants/{peasant}/improve

improve

Name	Requirement	Type	Description
peasant	\d+	integer	peasant id
x	\d+	integer	x coordinate of target plot
y	\d+	integer	y coordinate of target plot

POST /peasants/{peasant}/man

man common building

Name	Requirement	Type	Description
peasant	\d+	integer	peasant id
x	\d+	integer	x coordinate of target plot
y	\d+	integer	y coordinate of target plot

POST /peasants/{peasant}/plant/{what}

plant field

Name	Requirement	Type	Description
peasant	\d+	integer	peasant id
x	\d+	integer	x coordinate of target plot
y	\d+	integer	y coordinate of target plot
what

POST /peasants/{peasant}/repair

repair

Name	Requirement	Type	Description
peasant	\d+	integer	peasant id
x	\d+	integer	x coordinate of target plot
y	\d+	integer	y coordinate of target plot

POST /peasants/{peasant}/take

take land

Name	Requirement	Type	Description
peasant	\d+	integer	peasant id
x	\d+	integer	x coordinate of target plot
y	\d+	integer	y coordinate of target plot

POST /villages/{village}/postmessage

post a message to the village

Show/hide List Operations Expand Operations

Game Data

GET /buildings/{building}/details public

get building detail data

Documentation

Get building details

Requirements

Name	Requirement	Type	Description
building	\d+	integer	building id

Return

Parameter	Type	Versions	Description
200
id	integer	*
type	object (BuildingType)	*	type of the building
type[name]	string	*	name of this type
type[build_from]	object (Resource)	*	how much of what resource is needed to construct this building
type[build_from][name]	string	*	name of the resource, one of "wood", "stone" or "food"
type[build_from][amount]	integer	*	amount of the resource (e.g. required amount, stored amount, etc.)
damage	integer	*	damage (in resource amount)
death	boolean	*	did someone die here last night?
resources[]	array of objects (Resource)	*	resources stored inside
resources[][name]	string	*	name of the resource, one of "wood", "stone" or "food"
resources[][amount]	integer	*	amount of the resource (e.g. required amount, stored amount, etc.)

GET /families/{family} public

get family data

Parameter	Type	Versions	Description
200

GET /families/{family}/details private

get family data

Documentation

Get detail information about your family

Requirements

Name	Requirement	Type	Description
family	\d+	integer	family id

Return

Parameter	Type	Versions	Description
200
id	integer	*
name	string	*	family name
peasants[]	array of objects (Peasant)	*	all members of the family, parents first, then children
peasants[][id]	integer	*
peasants[][name]	string	*	first name
peasants[][adult]	boolean	*	is this peasant an adult (true) or a child (false)
peasants[][male]	boolean	*	is this peasant a man/boy (true) or a woman/girl (false)
peasants[][alive]	boolean	*	is this peasant alive
peasants[][hunger]	integer	*	hunger severity (0 = not hungry)
peasants[][current_action]	object (Action)	*	current action of this peasant
peasants[][current_action][id]	integer	*
peasants[][current_action][type]	string	*	specifies the action, e.g. "gather", "build", etc.
peasants[][current_action][subtype]	string	*	specifies an optional detail for the action, e.g. what to gather or plant
peasants[][current_action][plot]	object (Plot)	*	the plot/target of the action
peasants[][current_action][plot][id]	integer	*
peasants[][current_action][plot][x]	integer	*	x coordinate on the map
peasants[][current_action][plot][y]	integer	*	y coordinate on the map
sleeping_home	object (Building)	*	where the family wants to sleep the next night
sleeping_home[id]	integer	*
sleeping_home[type]	object (BuildingType)	*	type of the building
sleeping_home[type][name]	string	*	name of this type
sleeping_home[plot]	object (Plot)	*	location of the building
sleeping_home[plot][id]	integer	*
sleeping_home[plot][x]	integer	*	x coordinate on the map
sleeping_home[plot][y]	integer	*	y coordinate on the map
sleeping_home[resources][]	array of objects (Resource)	*	resources stored inside
sleeping_home[resources][][name]	string	*	name of the resource, one of "wood", "stone" or "food"
sleeping_home[resources][][amount]	integer	*	amount of the resource (e.g. required amount, stored amount, etc.)

GET /families/{family}/diary private

get a diary

Documentation

Get a diary

Requirements

Name	Requirement	Type	Description
family	\d+	integer	family id
village	\d+	integer	village id

Return

Parameter	Type	Versions	Description
200
day	integer	*	day of this entry
entry	string	*	text of this entry

POST /families/{family}/writediary

write todays diary entry (overwrites if exists)

GET /villages/available public
- get available games
Documentation

Get list of available villages (i.e. open games)

Name	Requirement	Type	Description
text		string	the text of the diary entry
family

POST /villages/create public

Create a private game

Name	Requirement	Type	Description
password		string	password that will be needed to join this game
pvp		string	will this be a PvP (true) or Cooperative (false) game?
plots		string	will families start with plots or not? (true/false)
turntime	\d+	integer	hours between turns. Allowed values: 12, 24 or 48
density	\d+	integer	how many families to have in the village

POST /villages/{village}/checkpass private

check if your password for a game is correct

GET /villages/{village}/details public

get village detail data

Documentation

Get basic information about a village

Requirements

Name	Requirement	Type	Description
village	\d+	integer	village id

Return

Parameter	Type	Versions	Description
200
id	integer	*
name	string	*	village name
day	integer	*	current day in the village
season	integer	*	current season (0 = summer, 1 = autum, 2 = winter)
hours	integer	*	how many hours until a turn is forced even if not all players issued orders

GET /villages/{village}/diaries public

Get all the diary entries of a village. Only available after the game has ended

GET /villages/{village}/events/{day} private

get events of a specific day in this village

GET /villages/{village}/map public

get map data

Documentation

Get map data for a village

Requirements

Name	Requirement	Type	Description
village	\d+	integer	village id

Return

Parameter	Type	Versions	Description
200
id	integer	*
name	string	*	village name
pvp	boolean	*	is PvP (attacking buildings) enabled?
land	boolean	*	start with ground or not (just hut) ?
day	integer	*	current day in the village
season	integer	*	current season (0 = summer, 1 = autum, 2 = winter)
forestry	integer	*	how many gather wood actions have been done (used by clients to display a dwindling forest, pure optics, no game effect)
deaths	integer	*	how many peasants died last night (used by the client to display a burial counter)
hours	integer	*	how many hours until a turn is forced even if not all players issued orders
plots[]	array of objects (Plot)	*	all plots belonging to this village
plots[][id]	integer	*
plots[][x]	integer	*	x coordinate on the map
plots[][y]	integer	*	y coordinate on the map
plots[][status]	string	*	current status of the plot (i.e. what is there?)
plots[][value]	integer	*	numerical value used for various purposes (amount of food on fields, ownership on sample map, etc.)
plots[][tracks]	array	*	what kind of tracks are on this plot
plots[][total_tracks]	integer	*	total number of creatures that came across this plot
plots[][building]	object (Building)	*	building on this plot, if any
plots[][building][id]	integer	*
plots[][building][type]	object (BuildingType)	*	type of the building
plots[][building][type][name]	string	*	name of this type
plots[][building][type][health]	integer	*	how much damage the building can take before becoming ruined
plots[][building][type][house]	boolean	*	whether it is a house or not (i.e. something that can be slept in)
plots[][building][type][fence]	boolean	*	whether it is a fence or not (i.e. something that needs to be connected to neighbours to be effective)
plots[][building][type][build_from]	object (Resource)	*	how much of what resource is needed to construct this building
plots[][building][type][build_from][name]	string	*	name of the resource, one of "wood", "stone" or "food"
plots[][building][type][build_from][amount]	integer	*	amount of the resource (e.g. required amount, stored amount, etc.)
plots[][building][plot]	object (Plot)	*	location of the building
plots[][building][common]	boolean	*	whether it is a community building or not
plots[][building][damage]	integer	*	damage (in resource amount)
plots[][building][death]	boolean	*	did someone die here last night?
plots[][building][resources][]	array of objects (Resource)	*	resources stored inside
plots[][building][resources][][name]	string	*	name of the resource, one of "wood", "stone" or "food"
plots[][building][resources][][amount]	integer	*	amount of the resource (e.g. required amount, stored amount, etc.)
plots[][total_actions]	integer	*	total number of actions executed on this plot
plots[][owner]	object (Family)	*	family that owns this plot
plots[][owner][id]	integer	*
plots[][owner][name]	string	*	family name

GET /villages/{village}/messages private

get messages posted to this village

Name	Requirement	Type	Description
village

GET /villages/{village}/monsters private

get monsters roaming this village

Name	Requirement	Type	Description
village

GET /villages/{village}/recentevents private

get recent (last turn) events in this village

GET /villages/{village}/stats public

Get the village statistics

GET /villages/{village}/survivors public

Get the list of all families and their death days

Show/hide List Operations Expand Operations

Market

POST /market/exchange/{family}

exchange karme for resources

POST /market/finalizetxn

buy gold coins from in-game store (deprecated)

Name	Requirement	Type	Description
orderid	\d+	integer	order ID

POST /market/inittxn

buy gold coins from in-game store (deprecated)

Name	Requirement	Type	Description
amount	\d+	integer	amount of gold coins to buy

Show/hide List Operations Expand Operations

Statistics

GET /statistics/build/{family} private

get building statistics

GET /statistics/gather/{family} private

get gathering statistics

- - GET /announcements/
    - get current announcements
    Documentation
    
    Get the current announcements, newest first

API documentation

Account Management

GET /account/

Documentation

Return

200

POST /account/changemail

Documentation

Requirements

POST /account/changename

Documentation

Requirements

POST /account/forgotten

Documentation

Requirements

Return

200

POST /account/register

Documentation

Requirements

Return

200

POST /families/instant

Documentation

POST /families/{family}/take

Documentation

Requirements

Parameters

Actions

POST /families/{family}/resources

Requirements

POST /families/{family}/sethome/{home}

Requirements

POST /peasants/{peasant}/attack

Documentation

Requirements

POST /peasants/{peasant}/build/{what}

Documentation

Requirements

POST /peasants/{peasant}/clear

Documentation

Requirements

POST /peasants/{peasant}/foundation

Documentation

Requirements

POST /peasants/{peasant}/gather/{what}

Documentation

Requirements

POST /peasants/{peasant}/harvest

Documentation

Requirements

POST /peasants/{peasant}/improve

Documentation

Requirements

POST /peasants/{peasant}/man

Documentation

Requirements

POST /peasants/{peasant}/plant/{what}

Documentation

Requirements

POST /peasants/{peasant}/repair

Documentation

Requirements

POST /peasants/{peasant}/take

Documentation

Requirements

POST /villages/{village}/postmessage

Requirements

Game Data

GET /buildings/{building}/details public

Documentation

Requirements

Return

200

GET /families/{family} public

Documentation

Requirements

Return

200

GET /families/{family}/details private