There are still some mentions of old error codes on this page, please ignore them. Errors are now string constants instead. Eventually we will update the error documentation for all endpoints
Most actions require authentication using an API key. Add the header Authorization: Bearer <api key> to your requests, where <api key> is the API key from StaffCP.
All UUIDs returned by the API are without dashes. The API also accepts only UUIDs without dashes.
The API will also return whether there was an error or not, with the error field (either true or false). If true, there will also be a message field containing the error message and sometimes a meta field (should be a string but due to a bug sometimes other types) containing more information about the error.
{user}| Format | Example |
|---|---|
id:<nameless user id> |
id:3 |
username:<nameless username> |
username:Samerton |
integration_id:<integration name>:<account id for linked service> |
integration_id:minecraft:09948878fe2044e3a07242c39869dd1f |
integration_name:<integration name>:<account username for linked service> |
integration_name:discord:Derkades#9976 |
/infoReturns general information about this NamelessMC instance. No parameters required. Response:
Response:
nameless_version - string: NamelessMC version, e.g. 2.0.0-pr13version_update - object, optional
language - Default language stringmodules - array: list of names of enabled modules/users/{user}/announcementsReturns all announcements the specified user can see.
Reponse:
announcements
id int - announcement idheader string - announcement header/titlemessage string - announcement contentpages string array - pages where the announcement is displayedgroups int array - groups to which the announcement is shown/users/registerThe users/register action will register a specified user.
Request:
usernameemailintegrations (json object, may contain none, one, or multiple integrations)
<integration name> (like "Minecraft" or "Discord"):
id (uuid / discord id / something else)username (minecraft username / discord username / something else)Example, registering from Discord:
{
"username": "Derkades",
"email": "me@example.com",
"integrations": {
"Discord": {
"identifier": "183954832485253121",
"username": "Derkades#9976"
}
}
}
Example, registering from Minecraft:
{
"username": "Derkades",
"email": "me@example.com",
"integrations": {
"Minecraft": {
"identifier": "09948878fe2044e3a07242c39869dd1f",
"username": "Derkades"
}
}
}
Response:
link - string, optional - Link to set password. If email verification is enabled, the user will receive an email with this link instead.Error codes:
/users/{user} The users/{user} action will retrieve information about a specified user.
The output is a JSON object
exists - bool, if false no other values are presentidusernamelanguage_idlanguagedisplayname - (can this be null?)uuidregistered_timestamplast_online_timestampbanned - boolvalidated - bool, whether the account is verifieduser_title - (what is this? no one knows)
discord_id - discord user id as string if linked, otherwise nullgroups - list of json objects
idnamestafforderingame_rank_namediscord_role_idprofile_fields - json object map, key is profile field id
nametype - int (1=text, 2=textarea, 3=date)public - boolrequired - booldescription - stringvalue - TODO always string?integrations documentation TODO/groupsRequest:
id NamelessMC ID of group.name NamelessMC name of group.Response:
groups array of objects, ordered by order, ascending.
id int - group idname string - group namestaff boolorder intingame_rank_name stringdiscord_role_id string/users/{user}/groups/addRequest:
user - the NamelessMC ID of the usergroups - json array of website group IDs to add to this userErrors: TODO
/users/{user}/groups/removeRequest:
user number - the NamelessMC ID of the usergroups number array - website group IDs to remove from this userErrors: TODO
/reports/createThe reports/create action will create a report about a given user. The required POST body is a JSON object with the following keys:
reporter - NamelessMC user ID of the user creating the reportcontent - the reason for the report's creation (max 255 characters)reported - NamelessMC user ID of the user being reported (optional)reported_username - a username to display for the user being reported, if reported is not provided (optional)reported_uid - a unique ID for the user being reported, if reported is not provided (optional)server_id - the server ID the report is associated with, these values can be found in the StaffCP -> Integrations -> Minecraft -> Minecraft Servers section - New in 2.2.0Note, if reported is not provided, then both reported_username AND reported_uid must be provided
Errors:
19 - Report content too long
16 - reporter or reported invalid
21 - reporter is banned
26 - reporter == reported
23 - unable to create report
/users/{user}/notificationsThe users/{user}/notifications action will return a list of alerts a user has.
Response:
notifications array of objects
messageurltypeNotification types:
message - A new private message for the userlike - Someone has liked a post by the user (coming soon)profile_post - Someone has left a comment on the user's profileprofile_post_reply - Someone has replied to a comment on a profilethread-reply - Someone has posted in a thread the user is watching (coming soon)follow - Someone has followed the user (coming soon)Errors: TODO
/minecraft/server-infoThe minecraft/server-info action is used by the Minecraft plugin to send server information to the website.
Please note that this API description is currently just a random collection of data that happens to be sent by the official in-game Minecraft plugin, the website doesn't use all this data.
Request:
server_id int, requiredmax_memory intfree_memory intallocated_memory intmax_players int (on some platforms)motd string (on some platforms)tps floatgroups string array - all server groups, used for group sync dropdownplayers object
<uuid>
name string, requiredip stringgroups string arrayplaytime int - in minuteslocation object
world stringx inty intz intplaceholders object - placeholder key/values to be used for leaderboards/minecraft/update-groupsSends in-game groups for players so the website can perform group sync (if configured). It is up to the client to decide how often to send the request, and which players to include in the request. Generally, aim to send these requests only when groups have actually changed, and to send multiple players as a batch in a single request.
Request:
server_id int - Minecraft server IDplayer_groups (object, using player uuid as key)
groups - List of all group names/users/{user}/update-usernameThe users/{user}/update-username action will update the website username of a user with a given NamelessMC ID.
Request:
username - new username for userErrors: TODO
/users/{user}/banErrors: TODO
/users/{user}/verifyVerify a user (traditionally "email" verification).
Request:
code - Verification codeErrors:
/usersRequest:
limit - Max number of users to return in response. Defaults to 15. Set to 0 to disable.Possible filter parameters:
banned (boolean)verified (boolean)discord_linked (boolean)group_id (integer)operator ('AND' (default) or 'OR') - Whether all filters must apply (AND) or at least one (OR)Response:
users array
id intusername stringbanned boolverified boolintegrations objectTODO: Document integration data
TODO: Website may return more fields than mentioned here
Errors: ?
/discord/submit-role-listRequest:
roles array of objects
id string (!)name stringErrors: TODO
/discord/update-bot-settingsUpdates discord bot settings. Not all parameters below have to be present, it is possible to only change one setting by specifying one parameter.
Request:
url - New Discord bot URLguild_id - New Discord server ID to be associated with your website (as a string)bot_username Username#1234 of this botbot_id Discord user ID of the bot (as a string)Errors:
/discord/update-usernamesRequest:
users array of json objects:
id int - discord user idname string - discord usernameError codes?
/discord/set-rolesRequest:
user - NamelessMC idroles - Json array of discord role idsErrors: TODO
/integration/verifyRequest:
integration string - Integration type, for now "Minecraft" or "Discord" but this will probably change to an intcode string - Verification codeidentifier string - Unique identifier, such as a UUID or numerical idusername string - Display name, such as a Minecraft or Discord usernameErrors:
core:invalid_integrationcore:invalid_codeWhen an error occurs, the response will contain an error field with one of the below error strings. Relevant errors are documented for each API endpoint. For reference, all errors are linked here.
/websend/commandsRequest:
server_idResponse:
commands array of json objects
id intcommand stringErrors: ?
/websend/consoleRequest:
server_id intcontent array of strings, one line per array elementErrors: ?
/users/{user}/add-creditsRequest:
credits float - The amount of credits to add example 5.99Errors:
store:invalid_credits_amount/users/{user}/remove-creditsRequest:
credits float - The amount of credits to remove example 5.99Errors:
store:invalid_credits_amount/store/categoriesResponse:
categories array of categories - Returned in order
id intname stringhidden bool - If the category is hidden but can still be accesseddisabled bool - Category is disabled including all products/store/productsResponse:
products array of products - Returned in order
id intcategory_id intname stringprice floatprice_cents inthidden bool - If the product is hidden but can still be accesseddisabled bool - Product is disabled/store/paymentsPayment status ids:
0 Pending Payment1 Payment Complete2 Payment Refunded3 Payment Changebacked4 Payment DeniedRequest:
order int - Order id (Optional)gateway int - Gateway id (Optional)status int - Payment Status id (Optional)customer int - Customer id (Optional)recipient int - Customer id (Optional)limit int - Limit the amount of payments returned (Optional)Response: (Sorted by latest payments)
payments array of payments
id intorder_id intgateway_id inttransaction string, nullableamount stringamount_cents intcurrency stringfee stringstatus_id intcreated int - Timestamp of payment creationlast_updated int - Timestamp last time the payment was updated by the gateway providercustomer json object - The who paid for it
customer_id intuser_id int/nullusername string/nullidentifierstring/nullrecipient json object - The customer who is receiving the items bought
customer_id intuser_id int/nullusername string/nullidentifierstring/nullproducts array - List of the bought products
id int - Product idname int - Product name/store/pending-commandsRequest:
connection_id int - The connection id, Example the connection id to your minigame serverResponse:
online_mode bool - If the website is using uuid linking or notcustomers array
customer_id intuser_id int/nullidentifier string/nullusername stringcommands array - List of commands to execute with is returned in order
id intcommand stringorder_id intrequire_online bool - If player need to be online or not/store/commands-executedRequest:
commands int array - List of command id's that are executed{form}Can be form id or url path without /
{submission}Submission id
/formsResponse:
forms array - List of all forms
ìd inturl string - Url path example /applyurl_full string - Full link to form pagetitle stringcaptcha boolcomment_status int - The status will be set when user comment on their submission (Default 0 for disabled)/forms/{form}Response:
ìd inturl string - Url path example /applyurl_full string - Full link to form pagetitle stringcaptcha boolcomment_status int - The status will be set when user comment on their submission (Default 0 for disabled)fields array - The list of fields for this form
id intname stringtype int - field typerequired bool - Required to be filledmin int - Maximum charactersmax int - Minimum charactersplaceholder string/nulloptions string/nullinfo string/null/forms/submissionsFilter options:
form int - Form iduser_id int - Submissions by this userupdated_by_user int - Submissions updated by this userstatus int - Status idlimit int - Limit the amount of submissions returnedResponse: (Ordered by newest submissions)
submissions array - List of all requested submisssions
id intform_id intuser_id int/null - User id (null if posted by guest)updated_by int/null - User id (null if posted by guest)created int - Timestamplast_updated int - Timestampstatus_id int/forms/submissions/{submission}Response:
id intform json object
id int - Form idtitle string - Form titleuser json object
id int/null - User id (null if posted by guest)username string - Username/Guest/Deleted Usercreated int - Timestamplast_updated int - Timestampstatus json object
id int - Status idname string - Status nameopen int - If submission is open or closedfields array - List of fields
question string - The field questionfield_type intanswer string - The user input/forms/{form}/submissions/createRequest:
user user transformer (Optional - Guest if not inserted)field_values json object list - Key is field id and value is answer
field_id:answer (Example "14":"This is a example")field_id:array (Example "15":["Option 1", "Option 3", "Option 10"])Response:
submission_id intlink string - Full link to submission (User might not have permission to view){suggestion}/suggestions/{suggestion}Response:
id intauthor json object
id int - User idlink string - Suggestion URLusername string - Username/Deleted Userupdated_by json object
id int - User idusername string - Username/Deleted Userstatus json object
id int - Status idname string - Status nameopen bool - If suggestion is open or closedcategory json object
id int - Category idname string - Category nametitle string - Suggestion Titlecontent string - Suggestion content (Use \n for new lines)views int - The amount of viewscreated int - Timestamplast_updated int - Timestamplikes_count int - The amount of likesdislikes_count int - The amount of dislikeslikes array - List of user_id'sdislikes array - List of user_id's/suggestions/{suggestion}/likeRequest:
user user transformerlike bool - true to set, false to remove (Optional - Default true)/suggestions/{suggestion}/dislikeRequest:
user user transformerdislike bool - true to set, false to remove (Optional - Default true)/suggestions/{suggestion}/commentRequest:
user user transformercontent string - Comment content (Use \n for new lines)/suggestions/createRequest:
user user transformertitle string - Suggestion titlecontent string - Suggestion content (Use \n for new lines)category int - Category id (Optional - Default Unassigned)Response: same as /suggestions/{suggestion}