These docs are for v4.3.22. Click to read the latest docs for v4.4.0.

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}

🚧

Note:

Please keep in mind that in order to create the token the username and password must be to an admin account.

On another note, if you ever need to or just want to destroy a token then you would use this URL
http://IP-ADDRESS-OF-SERVER:RESTAPI-PORT/token/destroy/{token}?token={token}

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 CodeMeaning
HTTP 200The command succeed and the return may also include a "response" message.
HTTP 400There was an error and the return will include an error message providing additional information about the failure.
HTTP 401A secure endpoint (which requires an authenticated token) was used without supplying an authenticated token.
HTTP 403Returned solely by the token creation endpoint, this value indicates that the supplied credentials are invalid.
HTTP 404The 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
- 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
}