API

1. Basics

• There are exactly 6 endpoints: https://territorial.io/api/gold/send, https://territorial.io/api/account/get, https://territorial.io/api/account/create, https://territorial.io/api/chat/send, https://territorial.io/api/clan/stats/get and https://territorial.io/api/gold/seize. Only unlocked accounts can use /api/gold/seize (see 8).
• Every request uses the HTTP method POST. The request body is a JSON object.
• Every response is a JSON object with the HTTP status 200. The field status says whether the request was successful ("ok") or which error occurred (see Status values).
• The API allows requests from websites of other domains (CORS: Access-Control-Allow-Origin: *).

1.1 Authentication

Every request contains the account name and the password of the account that makes the request. This account pays the API fees.

Allowed characters are a–z, A–Z, 0–9, _ and -. Uppercase and lowercase letters are different characters.

1.2 Account activity

Every request with a correct password counts as activity of the requesting account. The account view of this account then shows "Last active some seconds ago."

2. API fees

Every request with a correct password costs Gold. The server removes the fee from the requesting account before it processes the request.

2.1 Base fee

The base fee depends on the number of API requests of all accounts together in the current minute. The counter is reset to 0 every minute.

Every successful response contains the field api_fees_cents: the API fee of this request in 0.01 Gold (base fee + extra fee, without the transaction fee).

2.2 When the fee is charged

3. /api/gold/send

Sends Gold from the requesting account to another account.

3.1 Request

{
  "account_name": "AbC12",
  "password": "xxxxxxxxxxxxxxx",
  "target_account_name": "Zy-9_",
  "amount": 25,
  "reference": 1042
}

3.2 Response

A transfer over the API is a normal transaction. In addition to the API fee, the sender pays the transaction fee of 0, 1 or 2 Gold, exactly as for a transfer in the game. The transaction fee is not an API fee and is not included in api_fees_cents. A transfer over the API also counts for the number of recent transactions that sets the transaction fee. See Transactions.

The sender pays amount + transaction fee + API fee. If the balance is too low for amount + transaction fee, the response is transaction error. The API fee is charged in this case. Every transfer appears in the transactions log.

The field reference is optional. Without it, or with an empty string, the transfer has no reference. A reference appears in the transactions log at the end of the line, after the usernames:

• Most accounts may only use a whole number from 0 to 999,999,999,999, for example an order number. It can be a JSON number or a string that contains only digits (at most 12).
• A few accounts are unlocked for text references. Their reference can be any text: the server replaces control characters with spaces and removes the characters `, < and >. After this removal, the text must have 1 to 140 characters.
• If the reference does not follow these rules, the response is reference error. No Gold is sent, but the API fee is charged.

4. /api/account/get

Returns the data of any account.

4.1 Request

4.2 Response

The response contains status, api_fees_cents and the object account_data. All ranks start at 0: rank 0 is the first place.

4.3 Online fields

online_status is only meaningful when last_online is 0.

5. /api/account/create

Creates a new account. The new account gets the same password as the requesting account.

5.1 Request

{
  "account_name": "AbC12",
  "password": "xxxxxxxxxxxxxxx"
}

5.2 Response

5.3 The new account

• The server chooses the account name at random. The requesting account cannot choose the account name.
• The password of the new account is the password that the requesting account has at the time of the request. Login with the new account name and this password.
• The username of the new account is Player, followed by a space and a number from 0 to 999.
• The new account has 0.00 Gold, no clan, no email address and 0 points in all rankings.
• The request does not send Gold to the new account. To send Gold, use /api/gold/send.

6. /api/chat/send

Writes a message from the requesting account in the lobby chat.

6.1 Request

{
  "account_name": "AbC12",
  "password": "xxxxxxxxxxxxxxx",
  "message": "Hello lobby!",
  "lobby": 1
}

6.2 Response

6.3 Rules

• The server replaces control characters, for example line breaks and tabs, with spaces.
• The server removes the characters `, < and > from the text.
• After this removal, the text must have 1 to 255 characters. Otherwise, the response is message error.
• An account that is muted in the lobby chat cannot write. The response is muted. See Reports.
• The requesting account does not need multiplayer play time. It does not need to be in the lobby.
• The lobby chat shows the message with [Bot] in front of the username of the requesting account. Example: the username Alice is shown as [Bot] Alice. If the username is empty, the lobby chat shows [Bot] in front of the account name.
• Only players who have the lobby chat open at this moment receive the message. Players who open the lobby chat later see the message among the last messages of the lobby chat.
• The message appears only in the chat of the lobby given in lobby. It does not appear in the chat of the other lobby.
• The response ok means that the server accepted the message and forwarded it to the lobby.
• Every message also appears in the public chat log territorial.io/log/chat, which shows the newest messages of the lobby chat.

7. /api/clan/stats/get

Returns the history of the clan points of 1 clan.

7.1 Request

7.2 Response

All times are UTC. A day starts at 00:00, a week starts on Sunday at 00:00, a month starts on the 1st at 00:00.

8. /api/gold/seize

Moves Gold from any account to the requesting account. Only accounts that are unlocked for this endpoint can use it. For every other account, the response is permission error. The list of unlocked accounts is not published.

8.1 Request

{
  "account_name": "AbC12",
  "password": "xxxxxxxxxxxxxxx",
  "target_account_name": "Zy-9_",
  "amount": 25,
  "reason": "Gold won by exploiting a bug"
}

8.2 Response

8.3 Rules

• If the target account has at least amount Gold, exactly amount Gold is moved.
• If the target account has less than amount Gold, the complete balance of the target account is moved, including amounts smaller than 1 Gold. The balance of the target account is then exactly 0 Gold.
• If the target account has 0 Gold, no Gold is moved. The response is ok with seized_cents 0. The seize does not appear in the transactions log.
• A seize never makes the balance of the target account negative.
• No transaction fee is charged, neither to the target account nor to the requesting account. The requesting account pays only the API fee.
• The target account cannot be the requesting account. In this case, the response is account error.
• The server replaces control characters in reason, for example line breaks and tabs, with spaces. The server removes the characters `, < and >. After this removal, the reason must have 1 to 200 characters. Otherwise, the response is reason error.
• The total amount of Gold that can be seized per day is limited. The limit counts the Gold that was actually moved (seized_cents), not amount. If the Gold that a seize would move exceeds this limit, the response is limit error and no Gold is moved.
• Every seize that moves more than 0 Gold appears in the transactions log with the action Seize, from the target account to the requesting account, with the fee 0.00 and the reason at the end of the line.

9. Status values

The field status has exactly 1 of these values:

10. Public logs and data pages

These pages are free, need no account and may be read by programs. /clans, /players, /log/chat, /log/reports and /log/transactions are plain text. The other logs under /log/ are HTML pages that contain the text in 1 <pre> element. In these other logs, newer entries are at the top. In /log/chat, /log/reports and /log/transactions, newer entries are at the bottom.

10.1 Request limit

• Do not send too many requests to these pages and to the wiki.
• If a program sends too many requests, the server answers with the HTTP status 403 and an empty body. The API endpoints in sections 3 to 8 are not affected.
• A program that receives 403 must stop all requests to these pages for 2 hours. Requests during this time extend the block.

A replay of a multiplayer game has the address https://territorial.io/log/?r=<ID>. The link to the replay appears at the end of each game.