User Management
GET /users[?page=]
This route returns all users currently existing on the system as a paginated result.
URL Parameters
?page=<id> (optional) — URL querystring indicating which page of pagination to show. e.g. /users?page=5
Responses
HTTP/200 — Returns paginated result.
{
"data": [
{
"id": 1,
"uuid": "ea39ae7d-17fb-4e89-ba7a-a41db3ceb7db",
"email": "dane@foobear.com",
"language": "en",
"root_admin": 1,
"use_totp": 0,
"created_at": "2016-01-12 03:34:07",
"updated_at": "2016-01-12 03:35:30"
},
{
"id": 10,
"uuid": "dd5ed5dd-bc29-4d2d-bdc8-dc9b1bc52f30",
"email": "dane@widgets.com",
"language": "en",
"root_admin": 0,
"use_totp": 0,
"created_at": "2016-01-15 04:47:58",
"updated_at": "2016-01-15 04:47:58"
}
],
"meta": {
"pagination": {
"total": 2,
"count": 2,
"per_page": 15,
"current_page": 1,
"total_pages": 1,
"links": []
}
}
}
GET /users/:id[?fields=]
Returns information about a single user.
URL Parameters
:id — The ID of the user to return information on.
?fields=<list> (optional) — A comma delimited list of database fields to return. e.g. ?fields=id,email
Responses
HTTP 200
{
"user": {
"id": 1,
"uuid": "ea39ae7d-17fb-4e89-ba7a-a41db3ceb7db",
"email": "dane@pterodactyl.io",
"language": "en",
"root_admin": 1,
"use_totp": 0,
"created_at": "2016-01-12 03:34:07",
"updated_at": "2016-01-12 03:35:30"
}
}
HTTP/400 — returned when the comma delimitated list of fields contains a field (or more) that do not exist.
{
"message": "There was an issue with the fields passed in the request.",
"status_code": 400
}
HTTP/404 — returned when no user by the requested ID exists on the system.
{
"message": "No user by that ID was found.",
"status_code": 404
}
POST /users
Creates a new account on the system.
Request Data
{
"email": "wuzzle@woo.com",
"password": "WuzzleWoo2",
"admin": false
}
Responses
HTTP/201 — returned when the user is successfully created on the system. A Location header is also returned with a link to the new user resource. (e.g. Location: https://pterodactyl.local/api/users/<id>)
HTTP/422 — returned when there is a validation error.
HTTP/503 — returned when the panel encounters an error while processing the request.
PATCH /users/:id
Updates corresponding fields in the database for a given user.
URL Parameters
:id — The ID of the user to return information on.
Request Data
{
"field": "foozle",
"anotherfield": "widgets"
}
Responses
HTTP/200 — returns a new JSON structure for the user with the newly updated fields.
HTTP/422 — response when the fields passed to the PATCH request did not pass validation.
{
"message": "A validation error occured.",
"errors": {
"email": [
"The email must be a valid email address."
]
},
"status_code": 422
}
HTTP/503 — returned when an error occurs within the panel trying to update a user; often happens if the user does not exist.
{
"message": "Unable to update a user on the system due to an error.",
"status_code": 503
}
DELETE /users/:id
Delete a user from the system. This request will fail if the user has active servers.
URL Parameters
:id — The ID of the user to remove from the system.
Responses
HTTP/204 — returned when the account is successfully deleted from the system.
HTTP/503 — returned when an error occurs while attempting to delete the account from the system.