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
- 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
}