TShock for Terraria

Suggest Edits

REST API Endpoints

 

Description

The REST API of tshock allows for increased functionality and interaction with the server through web-based commands.
The API works through what are called "end points" which are basically commands that are send to the server through a URL.

Note:

While most of this information is accurate (setting it up, acquiring a token), this documentation is quite old, and more endpoints have been added or changed. Please visit us in Slack if you require more assistance with the API.

Technical Information:

All responses by the API are JSON encoded.

Setting it all up

To use the API first it must be enabled. You can enable it through the config.json file that is created by the tshock server.
To enable the REST API find the following lines in the config.json file:
"RestApiEnabled": false,
"RestApiPort": 7878,

Change the "false" to "true" and restart the server.

Next you will have to create a token. A token is a unique string that identifies you to the server. To create a token visit the
following URL in your web-browser or, if you are a developer, get your program to access it:
http://IP-ADDRESS-OF-SERVER:RESTAPI-PORT/v2/token/create?username={username}&password={password}
If you ever need to destroy a token then you would use
http://IP-ADDRESS-OF-SERVER:RESTAPI-PORT/token/destroy/{token}?token={token}

It's important to note that REST tokens generated in this fashion will not be persisted across sessions.
If you want REST tokens that are usable across sessions (i.e., after server restarts), you can create Application REST Tokens in the TShock config.json file.

Note:

Your Application REST Token's name should be hard to guess!
Anyone who knows the token name can use it.

Restrict the permissions on the usergroup you assign to the user you use for your tokens in order to avoid security breaches!

"ApplicationRestTokens": {
    "This_Is_Your_Token_Name_And_Should_Be_Hard_To_Guess": {
      "Username": "This should be an existing username",
      "UserGroupName": "This should be the group belonging to the user"
    },
    "REST_BAN_MANAGER_TOKEN_61238": {
    	"Username": "REST_Banner",
    	"UserGroupName": "REST_Ban_Group"
    }
  }

Usage

End-points are fairly self-explanatory however a few things that may not be: When using the REST API the token
that you created in "setting it all up" must be appended as a parameter in about 90% of the end-points (these
will be shown in the references at the bottom of the page).

The API is used in the following manner:
http://IP-ADDRESS-OF-SERVER:RESTAPI-PORT/endpoint?token={token}

in other words, if you wanted to get a list of all the players that are currently on the server then you would
use it as such:
http://127.0.0.1:7878/lists/players?token={token}

or say you needed to add extra parameters to the call? This would be accomplished in the following method:
http://127.0.0.1:7878/v2/players/read?player=someplayer&token={token}

As you can see all parameters are simply separated by an ampersand (the & symbol).

End Points

Status codes

Status Code
Meaning

HTTP 200

The command succeed and the return may also include a "response" message.

HTTP 400

There was an error and the return will include an error message providing additional information about the failure.

HTTP 401

A secure endpoint (which requires an authenticated token) was used without supplying an authenticated token.

HTTP 403

Returned solely by the token creation endpoint, this value indicates that the supplied credentials are invalid.

HTTP 404

The endpoint does not exist.

Server Commands

/status

Description: Prints out a basic information about the servers status

Parameters: N/A

Returns:
name - Server name
port - Port the server is running on
playercount - Number of players currently online
players - Player names separated by a comma

/tokentest

Description: Tests the token to see if it is valid

Parameters:
token - The token to be tested

Returns:
response - A response message

/v2/token/create

Description: Creates an authenticated token for use with other endpoints

Parameters:
username - User with which to authenticate the token
password - User's password

%20 and + can be used to replace whitespace in usernames and passwords.

Returns:
HTTP 200 if the authentication succeeds
HTTP 403 if the authentication fails
response - Error message if the authentication failed, else an authenticated token.

200 response:
https://ip:port/v2/token/create?username=example&password=example
{
  "status": "200",
  "response": "Successful login",
  "token": "F7FCC991A229448AE73C6179DFD4815E73AD69BA44FA2A0063FCD6286BBCDAB4"
} 
 
403 response:
https://ip:port/v2/token/create?username=example&password=example
{
  "status": "403",
  "error": "Username or password may be incorrect or this account may not have sufficient privileges."
}

/v2/server/broadcast

Description: Performs a server broadcast to all players on the server

Parameters:
token - A valid token
msg - The message to broadcast
Returns:
response - A response message

/v2/server/off

Description: Shuts down the server

Parameters:
token - A valid token
confirm - A bool value confirming whether or not to shut down the server
nosave - A bool value indicating whether or not to save the world before shutting down the server

Returns:
response - A response message

/v2/server/status

Description: Prints out details about the status of the currently running server

Parameters:
players - A bool value indicating if the status response should include player information
rules - A bool value indicating if the status response should include rule information

<player filter> - values indicating player columns which players must match to be returned if player output is enabled

Returns:
name - Server name
port - Port the server is running on
playercount - Number of players currently online
maxplayers - The maximum number of players the server support
world - The name of the currently running world
players - (optional) an array of players including the following information: nickname, username, ip, group, active, state, team
rules - (optional) an array of server rules which are name value pairs e.g. AutoSave, DisableBuild etc

/v2/server/rawcmd

Description: Issues a raw command on the server just as if you typed it into the console.

Parameters:
token - A valid token
cmd - The command to execute on the server

Returns:
response - The response from the executed command
User Commands

/v2/users/activelist

Description: Returns a list of currently active users on the server

Parameters:
token - A valid token

Returns:
activeusers - List of active users separated by a tab character

/v2/users/read

Description: Returns information about a specified user

Parameters:
token - A valid token
type - (defaults to name) name, id or ip indicating what the "user" parameter refers to
user - The name, ip or id of a currently registered user

Returns:
group - The group the user belong's to
id - The user's ID
name - The name of the user
ip - The ip of the user

/v2/users/create

Description: Creates a user in the database

Parameters:
token - A valid token
type - (defaults to name) name, id or ip indicating what the "user" parameter refers to
user - The name of the user to register
password - The password you wish to assign to the user
group - The group you wish to assign to the user
ip - The ip you wish to assign to the user

Returns:
response - A response message

/v2/users/destroy

Description: Deletes a user from the database

Parameters:
token - A valid token
type - (defaults to name) name, id or ip indicating what the "user" parameter refers to
user - The name, ip or id of a currently registered user

Returns:
response - A response message

/v2/users/update

Description: Edits the settings of a user

Parameters:
token - A valid token
type - (defaults to name) name, id or ip indicating what the "user" parameter refers to
user - The name, ip or id of a currently registered user
password - The new password you wish to assign to that user (optional)
group - The new group you wish to assign to that user (optional)

Returns:
response - A response message

Ban Commands

/bans/create

Description: Bans a player from the server

Parameters:
token - A valid token
ip - The IP address of the user being banned (optional)
name - The username of the user being banned (optional)
reason - The reason for banning the user (optional)

Returns:
response - A response message

/v2/bans/read

Description: Displays information on a ban

Parameters:
token - A valid token
type - either "user" or "ip" depending
user - Either the username or the IP address

Returns:
name - The username of the player
ip - The IP address of the player
reason - The reason the player was banned

/v2/bans/destroy

Description: Removes a player/IP from the ban list

Parameters:
token - A valid token
ban- Either the username or the IP address
type - either "user" or "ip" depending

Returns:
response - A response message

/v2/bans/list

Description: Prints out all banned players currently in the database

Parameters:
token - A valid token

Returns:
bans - A array of all the currently banned players including: name, ip & reason

Player Commands

/v2/players/list

Description: Prints out all players that are currently on the server.

Parameters:
token - A valid token

Returns:
players - A list of all current players on the server, separated by a comma.

/v2/players/read

Description: Prints out detailed information about a player

Parameters:
token - A valid token
player - An active player's nickname

Returns:
nickname - The player's nickname
username - The player's username (if they are registered)
ip - The player's IP address
group - The group that the player belong's to
position - The player's current position on the map
inventory - A list of all items in the player's inventory
buffs - A list of all buffs that are currently affecting the player

/v2/players/kick

Description: Kicks a player from the server

Parameters:
token - A valid token
player - A current player's nickname
reason - The reason for kicking the player (optional)

Returns:
response - A response message

/v2/players/ban

Description: Bans a player from the server

Parameters:
token - A valid token
player - A current player's nickname
reason - The reason for banning the player (optional)

Returns:
response - A response message

/v2/players/kill

Description: Kills a player on the server

Parameters:
token - A valid token
player - A current player's nickname

Returns:
response - A response message

/v2/players/mute

Description: Mutes a player on the server

Parameters:
token - A valid token
player - A current player's nickname
reason - The reason for muting the player (optional)

Returns:
response - A response message

/v2/players/unmute

Description: Unmutes a player on the server

Parameters:
token - A valid token
player - A current player's nickname
reason - The reason for un-muting the player (optional)

Returns:
response - A response message

World Commands

/world/read

Description: Prints out a lot of information about the world being run on the server.

Parameters:
token - A valid token

Returns:
name - The world name
size - The dimensions of the world
time - The current time in the world
daytime - Bool value indicating whether it is daytime or not
bloodmoon - Bool value indicating whether there is a blood moon or not
invasionsize - The current invasion size

/world/meteor

Description: Spawns a meteor in the world

Parameters:
token - A valid token

Returns:
response - A response message

/world/bloodmoon/{bool}

Description: Turns blood moon on or off

Parameters:
token - A valid token

Returns:
response - A response message

/v2/world/save

Description: Saves the world. (Same as using the /save command in the console)

Parameters:
token - A valid token

Returns:
response - A response message

/v2/world/autosave/state/{bool}

Description: Turns the auto-save feature on or off

Parameters:
token - A valid token

Returns:
response - A response message

/v2/world/butcher

Description: Kills all NPCs on the map.

Parameters:
token - A valid token
killfriendly - Bool value indicating whether or not to kill friendly NPCs

Returns:
response - A response message

Group Commands

/v2/groups/create

Description: Creates a new group on the server

Parameters:
token - A valid token
group - The name of the new group
parent - The name of the new groups parent group
permissions - A comma separated list of permissions for the new group.
chatcolor - A color in R,G,B form e.g. 255,255,255

Returns:
response - A response message

Note:

Permissions prefixed with ! will become negated permissions which cancel the inheritance of a permission from parent groups

/v2/groups/destroy

Description: Destroys a existing group

Parameters:
token - A valid token
group - The name of the group to destroy

Returns:
response - A response message

/v2/groups/list

Description: Returns an array of the groups configured on the server

Parameters:
token - A valid token

Returns:
groups - An array of the groups configured on the server including: name, parent & chatcolor

/v2/groups/read

Description: Returns detailed information about the requested group

Parameters:
token - A valid token
group - The name of the group to return information about

Returns:
name - The name of the group
parent - The name of the parent of this group
chatcolor - The chat color of this group
permissions - An array of permissions assigned "directly" to this group
negatedpermissions - An array of negated permissions assigned "directly" to this group
totalpermissions - An array of the calculated permissions available to members of this group due to direct permissions and inherited permissions

/v2/groups/update

Description: Returns an array of the groups configured on the server

Parameters:
token - A valid token
group - The name of the group to update
parent - The new parent for the group (optional)
chatcolor- The new chat color for the group (optional)
permissions - The new permissions, comma separated and with ! prefix to indicate a negated permission, for the group (optional)

Returns:
response - A response message
Misc Information

{
 “status”: “200”,
 blah,
 blah
}
Suggest Edits

[Raw] REST Overview

 

BanCreate
Description: Create a new ban entry.
Permissions: tshock.rest.bans.manage
Nouns:
ip(Optional) [String] - The IP to ban, at least this or name must be specified.
name(Optional) [String] - The name to ban, at least this or ip must be specified.
reason(Optional) [String] - The reason to assign to the ban.
token(Required) [String] - The REST authentication token.
Example Usage: /bans/create?ip=ip&name=name&reason=reason&token=token

BanDestroyV2
Description: Delete an existing ban entry.
Permissions: tshock.rest.bans.manage
Nouns:
ban(Required) [String] - The search criteria, either an IP address or a name.
type(Required) [String] - The type of search criteria, 'ip' or 'name'. Also used as the method of removing from the database.
caseinsensitive(Optional) [Boolean] - Name lookups should be case insensitive.
token(Required) [String] - The REST authentication token.
Example Usage: /v2/bans/destroy?ban=ban&type=type&caseinsensitive=caseinsensitive&token=token

BanInfoV2
Description: View the details of a specific ban.
Permissions: tshock.rest.bans.view
Nouns:
ban(Required) [String] - The search criteria, either an IP address or a name.
type(Required) [String] - The type of search criteria, 'ip' or 'name'.
caseinsensitive(Optional) [Boolean] - Name lookups should be case insensitive.
token(Required) [String] - The REST authentication token.
Example Usage: /v2/bans/read?ban=ban&type=type&caseinsensitive=caseinsensitive&token=token

BanListV2
Description: View all bans in the TShock database.
Permissions: tshock.rest.bans.view
Nouns:
token(Required) [String] - The REST authentication token.
Example Usage: /v2/bans/list?token=token

GroupCreate
Description: Create a new group.
Permissions: tshock.rest.groups.manage
Nouns:
group(Required) [String] - The name of the new group.
parent(Optional) [String] - The name of the parent group.
permissions(Optional) [String] - A comma seperated list of permissions for the new group.
chatcolor(Optional) [String] - A r,g,b string representing the color for this groups chat.
token(Required) [String] - The REST authentication token.
Example Usage: /v2/groups/create?group=group&parent=parent&permissions=permissions&chatcolor=chatcolor&token=token

GroupDestroy
Description: Delete a group.
Permissions: tshock.rest.groups.manage
Nouns:
group(Required) [String] - The group name to delete.
token(Required) [String] - The REST authentication token.
Example Usage: /v2/groups/destroy?group=group&token=token

GroupInfo
Description: Display information of a group.
Permissions: tshock.rest.groups.view
Nouns:
group(Required) [String] - The group name to get information on.
token(Required) [String] - The REST authentication token.
Example Usage: /v2/groups/read?group=group&token=token

GroupList
Description: View all groups in the TShock database.
Permissions: tshock.rest.groups.view
Nouns:
token(Required) [String] - The REST authentication token.
Example Usage: /v2/groups/list?token=token

PlayerBanV2
Description: Add a ban to the database.
Permissions: tshock.rest.ban, tshock.rest.bans.manage
Nouns:
player(Required) [String] - The player to kick.
reason(Optional) [String] - The reason the user was banned.
token(Required) [String] - The REST authentication token.
Example Usage: /v2/players/ban?player=player&reason=reason&token=token

PlayerKickV2
Description: Kick a player off the server.
Permissions: tshock.rest.kick
Nouns:
player(Required) [String] - The player to kick.
reason(Optional) [String] - The reason the player was kicked.
token(Required) [String] - The REST authentication token.
Example Usage: /v2/players/kick?player=player&reason=reason&token=token

PlayerKill
Description: Kill a player.
Permissions: tshock.rest.kill
Nouns:
player(Required) [String] - The player to kick.
from(Optional) [String] - Who killed the player.
token(Required) [String] - The REST authentication token.
Example Usage: /v2/players/kill?player=player&from=from&token=token

PlayerList
Description: List all player names that are currently on the server.
No special permissions are required for this route.
Nouns:
token(Required) [String] - The REST authentication token.
Example Usage: /lists/players?token=token

PlayerListV2
Description: Fetches detailed user information on all connected users, and can be filtered by specifying a key value pair filter users where the key is a field and the value is a users field value.
No special permissions are required for this route.
Nouns:
token(Required) [String] - The REST authentication token.
Example Usage: /v2/players/list?token=token

PlayerMute
Description: Mute a player.
Permissions: tshock.rest.mute
Nouns:
player(Required) [String] - The player to mute.
token(Required) [String] - The REST authentication token.
Example Usage: /v2/players/mute?player=player&token=token

PlayerReadV3
Description: Get information for a user.
Permissions: tshock.rest.users.info
Nouns:
player(Required) [String] - The player to lookup
token(Required) [String] - The REST authentication token.
Example Usage: /v3/players/read?player=player&token=token

PlayerUnMute
Description: Unmute a player.
Permissions: tshock.rest.mute
Nouns:
player(Required) [String] - The player to mute.
token(Required) [String] - The REST authentication token.
Example Usage: /v2/players/unmute?player=player&token=token

ServerBroadcast
Description: Broadcast a server wide message.
No special permissions are required for this route.
Nouns:
msg(Required) [String] - The message to broadcast.
token(Required) [String] - The REST authentication token.
Example Usage: /v2/server/broadcast?msg=msg&token=token

ServerCommandV3
Description: Executes a remote command on the server, and returns the output of the command.
Permissions: tshock.rest.command
Nouns:
cmd(Required) [String] - The command and arguments to execute.
token(Required) [String] - The REST authentication token.
Example Usage: /v3/server/rawcmd?cmd=cmd&token=token

ServerMotd
Description: Returns the motd, if it exists.
No special permissions are required for this route.
Nouns:
token(Required) [String] - The REST authentication token.
Example Usage: /v3/server/motd?token=token

ServerOff
Description: Turn the server off.
Permissions: tshock.rest.maintenance
Nouns:
confirm(Required) [Boolean] - Required to confirm that actually want to turn the server off.
message(Optional) [String] - The shutdown message.
nosave(Optional) [Boolean] - Shutdown without saving.
token(Required) [String] - The REST authentication token.
Example Usage: /v2/server/off?confirm=confirm&message=message&nosave=nosave&token=token

ServerReload
Description: Reload config files for the server.
Permissions: tshock.rest.cfg
Nouns:
token(Required) [String] - The REST authentication token.
Example Usage: /v3/server/reload?token=token

ServerRestart
Description: Attempt to restart the server.
Permissions: tshock.rest.maintenance
Nouns:
confirm(Required) [Boolean] - Confirm that you actually want to restart the server
message(Optional) [String] - The shutdown message.
nosave(Optional) [Boolean] - Shutdown without saving.
token(Required) [String] - The REST authentication token.
Example Usage: /v3/server/restart?confirm=confirm&message=message&nosave=nosave&token=token

ServerRules
Description: Returns the rules, if they exist.
No special permissions are required for this route.
Nouns:
token(Required) [String] - The REST authentication token.
Example Usage: /v3/server/rules?token=token

ServerStatusV2
Description: Get a list of information about the current TShock server.
No special permissions are required for this route.
Nouns:
token(Required) [String] - The REST authentication token.
Example Usage: /v2/server/status?token=token

ServerTokenTest
Description: Test if a token is still valid.
No special permissions are required for this route.
Nouns:
token(Required) [String] - The REST authentication token.
Example Usage: /tokentest?token=token

UserActiveListV2
Description: Returns the list of user accounts that are currently in use on the server.
Permissions: tshock.rest.users.view
Nouns:
token(Required) [String] - The REST authentication token.
Example Usage: /v2/users/activelist?token=token

UserCreateV2
Description: Create a new TShock user account.
Permissions: tshock.rest.users.manage
Nouns:
user(Required) [String] - The user account name for the new account.
group(Optional) [String] - The group the new account should be assigned.
password(Required) [String] - The password for the new account.
token(Required) [String] - The REST authentication token.
Example Usage: /v2/users/create?user=user&group=group&password=password&token=token

UserDestroyV2
Description: Destroy a TShock user account.
Permissions: tshock.rest.users.manage
Nouns:
user(Required) [String] - The search criteria (name or id of account to lookup).
type(Required) [String] - The search criteria type (name for name lookup, id for id lookup).
token(Required) [String] - The REST authentication token.
Example Usage: /v2/users/destroy?user=user&type=type&token=token

UserInfoV2
Description: List detailed information for a user account.
Permissions: tshock.rest.users.view
Nouns:
user(Required) [String] - The search criteria (name or id of account to lookup).
type(Required) [String] - The search criteria type (name for name lookup, id for id lookup).
token(Required) [String] - The REST authentication token.
Example Usage: /v2/users/read?user=user&type=type&token=token

UserListV2
Description: Lists all user accounts in the TShock database.
Permissions: tshock.rest.users.view
Nouns:
token(Required) [String] - The REST authentication token.
Example Usage: /v2/users/list?token=token

UserUpdateV2
Description: Update a users information.
Permissions: tshock.rest.users.manage
Nouns:
user(Required) [String] - The search criteria (name or id of account to lookup).
type(Required) [String] - The search criteria type (name for name lookup, id for id lookup).
password(Optional) [String] - The users new password, and at least this or group must be defined.
group(Optional) [String] - The new group for the user, at least this or password must be defined.
token(Required) [String] - The REST authentication token.
Example Usage: /v2/users/update?user=user&type=type&password=password&group=group&token=token

WorldBloodmoon
Description: Toggle the status of blood moon.
Permissions: tshock.rest.causeevents
Verbs:
bloodmoon(Required) [Boolean] - State of bloodmoon.
Nouns:
token(Required) [String] - The REST authentication token.
Example Usage: /world/bloodmoon/{bloodmoon}?token=token

WorldButcher
Description: Butcher npcs.
Permissions: tshock.rest.butcher
Nouns:
killfriendly(Optional) [Boolean] - Should friendly npcs be butchered.
token(Required) [String] - The REST authentication token.
Example Usage: /v2/world/butcher?killfriendly=killfriendly&token=token

WorldMeteor
Description: Drops a meteor on the world.
Permissions: tshock.rest.causeevents
Nouns:
token(Required) [String] - The REST authentication token.
Example Usage: /world/meteor?token=token

WorldRead
Description: Get information regarding the world.
No special permissions are required for this route.
Nouns:
token(Required) [String] - The REST authentication token.
Example Usage: /world/read?token=token

WorldSave
Description: Save the world.
Permissions: tshock.rest.cfg
Nouns:
token(Required) [String] - The REST authentication token.
Example Usage: /v2/world/save?token=token

Suggest Edits

/bans/create

Create a new ban entry.

 
gethttp://server-ip:rest-port/bans/create
curl --request GET \
  --url http://server-ip/:rest-port/bans/create
var request = require("request");

var options = { method: 'GET',
  url: 'http://server-ip/:rest-port/bans/create' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://server-ip/:rest-port/bans/create")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://server-ip/:rest-port/bans/create");

xhr.send(data);
import requests

url = "http://server-ip/:rest-port/bans/create"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "Ban created successfully"
}
{
  "error": "Missing or empty ip, name parameter"
}

Query Params

ip
string

The IP to ban, at least this or name must be specified.

name
string

The name to ban, at least this or ip must be specified.

reason
string

The reason to assign to the ban.

 
Suggest Edits

/v2/bans/list

View all bans in the TShock database.

 
gethttp://server-ip:rest-port/v2/bans/list
curl --request GET \
  --url http://server-ip/:rest-port/v2/bans/list
var request = require("request");

var options = { method: 'GET',
  url: 'http://server-ip/:rest-port/v2/bans/list' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://server-ip/:rest-port/v2/bans/list")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://server-ip/:rest-port/v2/bans/list");

xhr.send(data);
import requests

url = "http://server-ip/:rest-port/v2/bans/list"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "bans": [
    {
      "name": "Nicatrontg",
      "ip": "192.168.1.31",
      "reason": "Banned for cheating in PvP!"
    },
    {
      "name": "Ijwu",
      "ip": "192.168.1.36",
      "reason": "Banned for winning in PvP!"
    }
  ]
}
 
Suggest Edits

/v2/bans/read

View the details of a specific ban.

 
gethttp://server-ip:rest-port/v2/bans/read
curl --request GET \
  --url http://server-ip/:rest-port/v2/bans/read
var request = require("request");

var options = { method: 'GET',
  url: 'http://server-ip/:rest-port/v2/bans/read' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://server-ip/:rest-port/v2/bans/read")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://server-ip/:rest-port/v2/bans/read");

xhr.send(data);
import requests

url = "http://server-ip/:rest-port/v2/bans/read"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "name": "Nicatrontg",
  "ip": "192.168.1.31",
  "reason": "Banned for cheating in PvP!"
}
{
  "error": "Missing or empty user parameter"
}

Query Params

ban
string

The search criteria, either an IP address or a name.

type
string

The type of search criteria, 'ip' or 'name'.

caseinsensitive
boolean

Name lookups should be case insensitive.

 
Suggest Edits

/v2/server/broadcast

Broadcast a server wide message.

 
gethttp://server-ip:rest-port/v2/server/broadcast
curl --request GET \
  --url http://server-ip/:rest-port/v2/server/broadcast
var request = require("request");

var options = { method: 'GET',
  url: 'http://server-ip/:rest-port/v2/server/broadcast' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://server-ip/:rest-port/v2/server/broadcast")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://server-ip/:rest-port/v2/server/broadcast");

xhr.send(data);
import requests

url = "http://server-ip/:rest-port/v2/server/broadcast"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
	"The message was broadcasted successfully"
}
{
	"error": "Missing or empty msg paramater."
}

Query Params

msg
string

The message to broadcast.

 
Suggest Edits

/v3/server/motd

Returns the motd, if it exists.

 
gethttp://server-ip:rest-port/v3/server/motd
curl --request GET \
  --url http://server-ip/:rest-port/v3/server/motd
var request = require("request");

var options = { method: 'GET',
  url: 'http://server-ip/:rest-port/v3/server/motd' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://server-ip/:rest-port/v3/server/motd")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://server-ip/:rest-port/v3/server/motd");

xhr.send(data);
import requests

url = "http://server-ip/:rest-port/v3/server/motd"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
	"motd": "The contents of the message of the day will be here."
}
{
	"error": "The motd.txt was not found."
}
 
Suggest Edits

/v2/server/off

Turn the server off.

 
gethttp://server-ip:rest-port/v2/server/off
curl --request GET \
  --url http://server-ip/:rest-port/v2/server/off
var request = require("request");

var options = { method: 'GET',
  url: 'http://server-ip/:rest-port/v2/server/off' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://server-ip/:rest-port/v2/server/off")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://server-ip/:rest-port/v2/server/off");

xhr.send(data);
import requests

url = "http://server-ip/:rest-port/v2/server/off"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
	"The server is shutting down"
}
{
	"error": "Missing or invalid confirm parameter"
}

Query Params

confirm
boolean

Required to confirm that actually want to turn the server off.

message
string

The shutdown message.

nosave
boolean

Shutdown without saving.

 
Suggest Edits

/v3/server/rawcmd

Executes a remote command on the server, and returns the output of the command.

 
gethttp://server-ip:rest-port/v3/server/rawcmd
curl --request GET \
  --url http://server-ip/:rest-port/v3/server/rawcmd
var request = require("request");

var options = { method: 'GET',
  url: 'http://server-ip/:rest-port/v3/server/rawcmd' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://server-ip/:rest-port/v3/server/rawcmd")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://server-ip/:rest-port/v3/server/rawcmd");

xhr.send(data);
import requests

url = "http://server-ip/:rest-port/v3/server/rawcmd"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
	-Command Output-
}
{
	"error": "Missing or invalid cmd parameter"
}

Query Params

cmd
string

The command and arguments to execute.

 
Suggest Edits

/v3/server/reload

Reload config files for the server.

 
gethttp://server-ip:rest-port/v3/server/reload
curl --request GET \
  --url http://server-ip/:rest-port/v3/server/reload
var request = require("request");

var options = { method: 'GET',
  url: 'http://server-ip/:rest-port/v3/server/reload' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://server-ip/:rest-port/v3/server/reload")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://server-ip/:rest-port/v3/server/reload");

xhr.send(data);
import requests

url = "http://server-ip/:rest-port/v3/server/reload"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
	"Configuration, permissions, and regions reload complete. Some changes may require a server restart."
}
 
Suggest Edits

/v3/server/restart

Attempt to restart the server.

 
gethttp://server-ip:rest-port/v3/server/restart
curl --request GET \
  --url http://server-ip/:rest-port/v3/server/restart
var request = require("request");

var options = { method: 'GET',
  url: 'http://server-ip/:rest-port/v3/server/restart' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://server-ip/:rest-port/v3/server/restart")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://server-ip/:rest-port/v3/server/restart");

xhr.send(data);
import requests

url = "http://server-ip/:rest-port/v3/server/restart"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
	"The server is shutting down and will attempt to restart"
}
{
	"error": "Missing or invalid confirm parameter"
}

Query Params

confirm
boolean

Confirm that you actually want to restart the server

message
string

The shutdown message.

nosave
boolean

Shutdown without saving.

 
Suggest Edits

/v3/server/rules

Returns the rules, if they exist.

 
gethttp://server-ip:rest-port/v3/server/rules
curl --request GET \
  --url http://server-ip/:rest-port/v3/server/rules
var request = require("request");

var options = { method: 'GET',
  url: 'http://server-ip/:rest-port/v3/server/rules' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://server-ip/:rest-port/v3/server/rules")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://server-ip/:rest-port/v3/server/rules");

xhr.send(data);
import requests

url = "http://server-ip/:rest-port/v3/server/rules"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
	"rules": "The rules will be here."
}
{
	"error": "The rules.txt was not found."
}
 
Suggest Edits

/v2/server/status

The status endpoint returns basic information about the server's status.

 
gethttp://server-ip:rest-port/v2/server/status
curl --request GET \
  --url http://server-ip/:rest-port/v2/server/status
var request = require("request");

var options = { method: 'GET',
  url: 'http://server-ip/:rest-port/v2/server/status' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://server-ip/:rest-port/v2/server/status")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://server-ip/:rest-port/v2/server/status");

xhr.send(data);
import requests

url = "http://server-ip/:rest-port/v2/server/status"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
	"name": 'Fizzbuzz',
  "port": 7777,
  "playercount": 3,
  "maxplayers": 13,
  "world": "Alaenna's Smile",
  "players": [
    "Alfonse",
    "Edward",
    "Winry"
  ],
  "rules": [
    "AutoSave": true,
    "DisableBuild": true
  ]
}
{
	"error": "Invalid request."
}

Query Params

players
boolean

Indicates if the response should include the player list.

rules
boolean

Indicates if the response should include game rules.

 
Suggest Edits

/tokentest

Test if a token is still valid.

 
gethttp://server-ip:rest-port/tokentest
curl --request GET \
  --url http://server-ip/:rest-port/tokentest
var request = require("request");

var options = { method: 'GET', url: 'http://server-ip/:rest-port/tokentest' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://server-ip/:rest-port/tokentest")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://server-ip/:rest-port/tokentest");

xhr.send(data);
import requests

url = "http://server-ip/:rest-port/tokentest"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
	"response": "Token is valid and was passed through correctly.",
  "associateduser": "myPlayerName"
}
 
Suggest Edits

/v2/users/activelist

Returns the list of user accounts that are currently in use on the server.

 
gethttp://server-ip:rest-port/v2/users/activelist
curl --request GET \
  --url http://server-ip/:rest-port/v2/users/activelist
var request = require("request");

var options = { method: 'GET',
  url: 'http://server-ip/:rest-port/v2/users/activelist' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://server-ip/:rest-port/v2/users/activelist")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://server-ip/:rest-port/v2/users/activelist");

xhr.send(data);
import requests

url = "http://server-ip/:rest-port/v2/users/activelist"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
	"activeusers": "Bob	Johnny	Victoria"
}
 
Suggest Edits

/v2/users/create

Create a new TShock user account.

 
gethttp://server-ip:rest-port/v2/users/create
curl --request GET \
  --url http://server-ip/:rest-port/v2/users/create
var request = require("request");

var options = { method: 'GET',
  url: 'http://server-ip/:rest-port/v2/users/create' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://server-ip/:rest-port/v2/users/create")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://server-ip/:rest-port/v2/users/create");

xhr.send(data);
import requests

url = "http://server-ip/:rest-port/v2/users/create"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
	"User was successfully created"
}
{
	"error": "Missing or empty user parameter"
}
{
	"error": "Missing or empty password parameter"
}

Query Params

user
string

The user account name for the new account.

group
string

The group the new account should be assigned.

password
string

The password for the new account.

 
Suggest Edits

/v2/users/destroy

Destroy a TShock user account.

 
gethttp://server-ip:rest-port/v2/users/destroy
curl --request GET \
  --url http://server-ip/:rest-port/v2/users/destroy
var request = require("request");

var options = { method: 'GET',
  url: 'http://server-ip/:rest-port/v2/users/destroy' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://server-ip/:rest-port/v2/users/destroy")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://server-ip/:rest-port/v2/users/destroy");

xhr.send(data);
import requests

url = "http://server-ip/:rest-port/v2/users/destroy"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "User deleted successfully"
}
{
  "error": "Missing or empty user parameter"
}

Query Params

user
string

The search criteria (name or id of account to lookup).

type
string

The search criteria type (name for name lookup, id for id lookup).

 
Suggest Edits

/v2/users/list

Lists all user accounts in the TShock database.

 
gethttp://server-ip:rest-port/v2/users/list
curl --request GET \
  --url http://server-ip/:rest-port/v2/users/list
var request = require("request");

var options = { method: 'GET',
  url: 'http://server-ip/:rest-port/v2/users/list' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://server-ip/:rest-port/v2/users/list")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://server-ip/:rest-port/v2/users/list");

xhr.send(data);
import requests

url = "http://server-ip/:rest-port/v2/users/list"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "users": [
    {
      "name": "Nicatrontg",
      "id": 1,
      "group": "superadmin"
    },
    {
      "name": "Ijwu",
      "id": 2,
      "group": "trustedadmin"
    }
  ]
}
 
Suggest Edits

/v2/users/read

List detailed information for a user account.

 
gethttp://server-ip:rest-port/v2/users/read
curl --request GET \
  --url http://server-ip/:rest-port/v2/users/read
var request = require("request");

var options = { method: 'GET',
  url: 'http://server-ip/:rest-port/v2/users/read' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://server-ip/:rest-port/v2/users/read")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://server-ip/:rest-port/v2/users/read");

xhr.send(data);
import requests

url = "http://server-ip/:rest-port/v2/users/read"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "group": "superadmin",
  "id": "1",
  "name": "Nicatrontg"
}
{
  "Missing or empty user parameter"
}

Query Params

user
string

The search criteria (name or id of account to lookup).

type
string

The search criteria type (name for name lookup, id for id lookup).

 
Suggest Edits

/v2/users/update

Update a users information.

 
gethttp://server-ip:rest-port/v2/users/update
curl --request GET \
  --url http://server-ip/:rest-port/v2/users/update
var request = require("request");

var options = { method: 'GET',
  url: 'http://server-ip/:rest-port/v2/users/update' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("http://server-ip/:rest-port/v2/users/update")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "http://server-ip/:rest-port/v2/users/update");

xhr.send(data);
import requests

url = "http://server-ip/:rest-port/v2/users/update"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "password-response": "Password updated successfully",
  "group-response": "Group updated successfully"
}
{
  "error": "Missing or empty user parameter"
}
{
  "error": "Missing or empty group, password parameter"
}

Query Params

user
string

The search criteria (name or id of account to lookup).

type
string

The search criteria type (name for name lookup, id for id lookup).

password
string

The users new password, and at least this or group must be defined.

group
string

The new group for the user, at least this or password must be defined.