Need help on the API?

URL guide

Blue - italic text can be hovered for additional info.

Brief guide to URL's

Some different url formats:


Input Formats

Input format is only used for POST-requests. On GET-requests input values are read normally from the url query string.

json
(default)
form
Input has typical form-data, x-www-form-urlencoded or similar format

Output Formats

json
(default)
txt
php print_r()
php
serialized php
dbg
php var_export()

Examples

If you are logged into the game you can try the following examples by just clicking the links:


Return data

The data you can expect back can be in different formats. But the structure never changes. Below a typical (shortened) structure in txt format. 

Array
(
    [info] => Array
        (
            [status] => success
            [time] => September 08, 2009 15:39:28
        )

    [data] => Array
        (
            [id] => 7160
            [money] => 0
            [food] => 0
            [research] => 5421
            [wood] => 16987
            [credits] => 5338224
        )
)

As you can see, it's a (sort of) multidimensional array with a simple key->value notation.
Shown are 2 main blocks but it's important to tell there are 3 of them. They are; info, data & errors. Info is the most reliable of the 3, this one is always shown with the same children; status & time. Data can hold several blocks or just 1 and every block might have more blocks in it. The example is very "flat" but a complex function will hold a lot more. Errors is the one not shown in the example. It will hold a list of errors but usually just 1, the most common one. Saying "You're not logged in".

Authenticating

Many of the functions require you to be authenticated, and a subset of those also require you to pass along an CSRF-token.

To authenticate, use the auth-login function (described below). In the response from this function you will recieve a new cookie, something similar to: PHPSESSID=6p8rlk5ot82tcrqq6agbfm95h3 This cookie has to be sent on all subsequent requests that requires authentication. The auth-session will expire after about one hour of inactivity.

The auth-login function will also return a CSRF-token in its normal response data. This token has to be sent on all subsequent requests that requires the token. It is sent in the X-Csrf-Token header. The token will expire if the auth-session expires.

Function reference

There is a big list of "functions" you can send to the API and it will always return data. There are actually several lists all defining a bit of their functionality and needs.

Default readable info on the user
Name Type CSRF Authed Needs Returns
user-info GET - Authed - id, username, email, logins, last_login, last_news, hours, next_attack, next_attack2, name, level, realname, country, date_signup, chat_token,
tribe-goods GET - Authed - id, money, food, research, wood, credits, market_money, market_food, market_soldiers, market_wood
tribe-builds GET - Authed - id, all buildings built, under constructions, land and incoming land
tribe-stats GET - Authed - id, tribe(name), race, fame, vote(elder), type(elder etc), reset_option, pause_start_tick, pause_end_tick, pause_reason, kills, invested, killed, alliance,
tribe-spells GET - Authed - id, power(mana), all running spells with their remaining times
tribe-ops GET - Authed - id, credits(thievery points), all running thievery ops with their remaining times
tribe-population GET - Authed - id, all units including citizens
tribe-home GET - Authed - Array of all units/citizens at home.
tribe-out GET - Authed - Array of all returning(invasion/exploring/thieving) citizens and military.
tribe-training GET - Authed - Array of all training citizens and military. + total
Default readable info on the user's alliance
Name Type CSRF Authed Needs Returns
alliance-rankings GET - Authed - id, alli_name, alli_desc, land, fame, kills, strength, power,
alliance-info GET - Authed - id, name, password, image, private, money, food, research, wood, soldiers, elder_message, vote_count, imagewidth, imageheight, bootcamp, description,
alliance-research GET - Authed - id, uninvested, and all research categories
alliance-users GET - Authed - 1, 2, etc.
alliance-size GET - Authed - size
alliance-id GET - Authed - id
Default readable info on the game
Name Type CSRF Authed Needs Returns
game-switches GET - - - vacation_mode, mergers, names, tribe_creation, alliance_creation, global_pause, login_stopper, bootcamp_signups, update_button, registration
game-year_oe GET - - - year_oe
game-alliances GET - - - 1, 2, etc.(only active alliances are counted so alliance 10 is/can be on number 5)
guide-races GET - - race (optional, default to 'all') Information about all races
guide-spells GET - - spell (optional, default to 'all') Information about all spells
guide-ops GET - - op (optional, default to 'all') Information about all operations
guide-spells GET - - - Infos about spells
guide-operations GET - - - Infos about operations
guide-attacks GET - - - Infos about attacks
News
Name Type CSRF Authed Needs Returns
news-tribe GET - Authed - id, name, length, items[]
news-alliance GET - Authed - id, name, length, items[]
news-global GET - - - length, items[]
Name Type CSRF Authed Needs Returns
auth-login POST - - username, password id, report, csrf_token
auth-logout POST CSRF-token Authed - report
market-buy POST CSRF-token Authed amount, good id, money, food, research, wood, credits, market_money, market_food, market_soldiers, market_wood
market-sell POST CSRF-token Authed amount, good id, money, food, research, wood, credits, market_money, market_food, market_soldiers, market_wood
search-default GET - Authed phrase, limit(optional) query, length, items[]
search-tribe GET - Authed phrase, limit(optional) query, length, items[]
search-page GET - Authed phrase, limit(optional) query, length, items[]
search-alliance GET - Authed phrase, limit(optional) id, length, items[]
archive-search GET - Authed str Some string stuff yet to clean up
archive-tribe GET - Authed id Some string stuff yet to clean up
archive-alliance GET - Authed id Some string stuff yet to clean up
archive-intel GET - Authed id Some string stuff yet to clean up
mail-read_inbox GET - Authed id post,id
mail-delete_inbox POST CSRF-token Authed id id
mail-unread_inbox POST CSRF-token Authed id id
mail-read_outbox GET - Authed id post,id
mail-delete_outbox POST CSRF-token Authed id id
mystics-cast POST CSRF-token Authed selSpellname, txtAmount, selTarget, minHours, chkStop(optional), chkMin(optional) result
forum-get_post GET - Authed id id, post
forum-get_plain GET - Authed id id, post
forum-edit_post POST CSRF-token Authed id, parent_id, value id, post
bugs-update POST CSRF-token Authed id, part, value id, part, value
bugs-categories GET - Authed default result
bugs-urgencies GET - Authed default result
bugs-statuses GET - Authed default result
bugs-assignees GET - Authed default result
bugs-delete_reply POST CSRF-token Authed id id
report-content POST CSRF-token Authed loc loc