Beacon Panel REST API v1 Documentation

Introduction

The Beacon Panel API allows you to programmatically manage your game servers, databases, files, schedules, backups, and more. This documentation provides comprehensive details about all available endpoints, authentication methods, and includes examples for each API call.

All API requests are made to endpoints beginning with the base URL /api/v1 and require authentication using a Bearer token.

Authentication

All API endpoints require authentication using a Bearer token in the Authorization header:

Authorization: Bearer YOUR_TOKEN_HERE

Obtaining a Token

You can obtain an API token from your Beacon Panel account settings page. API tokens have the same permissions as your user account, so be careful not to share them. If a token is compromised, you should revoke it immediately.

Example Authentication Request

curl -X GET "https://www.beaconhosting.org/api/v1/servers" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Response Format

All API responses follow a consistent format:

{
"success": true|false,
"data": {}, // Only present on success
"error": "Error message" // Only present on failure
}

Success Response Example

{
"success": true,
"data": {
  "id": "servers/123",
  "name": "Minecraft Server",
  "status": "running"
}
}

Error Response Example

{
"success": false,
"error": "Server not found"
}

HTTP Status Codes

Status Code	Description
200 OK	The request was successful
400 Bad Request	The request was malformed or contained invalid parameters
401 Unauthorized	Missing or invalid authentication token
403 Forbidden	The authenticated user does not have sufficient permissions
404 Not Found	The requested resource does not exist
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	An error occurred on the server

Servers

Returns a download URL for a specific backup.

GET/api/v1/servers/{serverId}/backups/{backup}/download

Returns a download URL for a specific backup.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server
backup	string	Yes	The backup identifier

Example Request

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}/backups/{backup}/download" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example Response

{
  "success": true,
  "data": {
    "downloadUrl": "https://..."
  }
}

Returns details about a specific backup.

GET/api/v1/servers/{serverId}/backups/{backup}

Returns details about a specific backup.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server
backup	string	Yes	The backup identifier

Example Request

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}/backups/{backup}" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example Response

{
  "success": true,
  "data": {
    "backupId": "backup-123",
    "name": "Daily Backup",
    "size": 1024000,
    "createdAt": "2025-04-15T18:30:00Z"
  }
}

Deletes a specific backup.

DELETE/api/v1/servers/{serverId}/backups/{backup}

Deletes a specific backup.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server
backup	string	Yes	The backup identifier

Example Request

curl -X DELETE "https://www.beaconhosting.org/api/v1/servers/{serverId}/backups/{backup}" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example Response

{
  "success": true,
  "data": {
    "message": "Backup deleted successfully"
  }
}

Returns a list of all backups for the specified server.

GET/api/v1/servers/{serverId}/backups

Returns a list of all backups for the specified server.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Request Body

Parameter	Type	Required	Description
name	string	No	The name parameter
ignored	string	No	The ignored parameter

Example Request

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}/backups" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "backup-123",
      "name": "Daily Backup",
      "size": 1024000,
      "createdAt": "2025-04-15T18:30:00Z"
    }
  ]
}

Creates a new backup for the specified server.

POST/api/v1/servers/{serverId}/backups

Creates a new backup for the specified server.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Request Body

Parameter	Type	Required	Description
name	string	No	The name parameter
ignored	string	No	The ignored parameter
name	string	No	The name for the backup (optional, defaults to 'API Backup')
ignored	string	No	Files or directories to ignore during backup (optional)

Example Request

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/backups" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "name": "example_name",
  "ignored": "example_ignored"
}'

Example Response

{
  "success": true,
  "data": {
    "message": "Backup created",
    "backupId": "backup-123"
  }
}

Retrieves recent console logs from the server.

GET/api/v1/servers/{serverId}/console

Retrieves recent console logs from the server.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Query Parameters

Parameter	Type	Required	Description
size	string	No	Number of items to return
size	number	No	Number of recent log lines to retrieve (default: 100, max: 1000)

Request Body

Parameter	Type	Required	Description
command	string	Yes	The command to execute

Example Request

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}/console" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example Response

{
  "success": true,
  "data": {
    "logs": [
      "[12:34:56] [Server thread/INFO]: Player joined the game",
      "[12:35:01] [Server thread/INFO]: Player left the game"
    ]
  }
}

Sends a command to the server console for execution.

POST/api/v1/servers/{serverId}/console

Sends a command to the server console for execution.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Query Parameters

Parameter	Type	Required	Description
size	string	No	Number of items to return

Request Body

Parameter	Type	Required	Description
command	string	Yes	The command to execute
command	string	Yes	The command to execute on the server console

Example Request

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/console" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "command": "say Hello from the API!"
}'

Example Response

{
  "success": true,
  "data": {
    "message": "Command executed"
  }
}

Rotates the password for a specific database.

POST/api/v1/servers/{serverId}/databases/{database}/rotate-password

Rotates the password for a specific database.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server
database	string	Yes	The database name

Example Request

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/databases/{database}/rotate-password" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json"

Example Response

{
  "success": true,
  "data": {
    "message": "Password rotated",
    "newPassword": "********"
  }
}

Deletes a specific database.

DELETE/api/v1/servers/{serverId}/databases/{database}

Deletes a specific database.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server
database	string	Yes	The database name

Example Request

curl -X DELETE "https://www.beaconhosting.org/api/v1/servers/{serverId}/databases/{database}" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example Response

{
  "success": true,
  "data": {
    "message": "Database deleted successfully"
  }
}

Returns a list of all databases for the specified server.

GET/api/v1/servers/{serverId}/databases

Returns a list of all databases for the specified server.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Request Body

Parameter	Type	Required	Description
database	string	Yes	The database name
remote	string	No	The remote parameter

Example Request

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}/databases" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "db-123",
      "name": "minecraft_db",
      "host": "localhost",
      "port": 3306
    }
  ]
}

Creates a new database for the specified server.

POST/api/v1/servers/{serverId}/databases

Creates a new database for the specified server.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Request Body

Parameter	Type	Required	Description
database	string	Yes	The database name
remote	string	No	The remote parameter
database	string	Yes	The name for the database
remote	string	No	Remote access configuration (optional)

Example Request

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/databases" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "database": "example_database",
  "remote": "example_remote"
}'

Example Response

{
  "success": true,
  "data": {
    "message": "Database created",
    "databaseId": "db-123"
  }
}

Compresses multiple files or directories into an archive.

POST/api/v1/servers/{serverId}/files/compress

Compresses multiple files or directories into an archive.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Request Body

Parameter	Type	Required	Description
files	array	Yes	The files parameter
root	string	No	The root parameter
files	array	Yes	Array of file or directory paths to compress
root	string	No	The root directory for the operation (defaults to '/')

Example Request

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/files/compress" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "files": "example_files",
  "root": "example_root"
}'

Example Response

{
  "success": true,
  "data": {
    "message": "Archive created",
    "archivePath": "/archive.tar.gz"
  }
}

Returns the contents of a specific file.

GET/api/v1/servers/{serverId}/files/contents

Returns the contents of a specific file.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Query Parameters

Parameter	Type	Required	Description
file	string	Yes	The file path to read

Example Request

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}/files/contents" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example Response

{
  "success": true,
  "data": {
    "content": "server-port=25565\ndifficulty=normal"
  }
}

Copies a file or directory to a new location.

POST/api/v1/servers/{serverId}/files/copy

Copies a file or directory to a new location.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Request Body

Parameter	Type	Required	Description
from	string	Yes	The from parameter
to	string	Yes	The to parameter
from	string	Yes	The source file or directory path
to	string	Yes	The destination path

Example Request

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/files/copy" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "from": "example_from",
  "to": "example_to"
}'

Example Response

{
  "success": true,
  "data": {
    "message": "File copied successfully"
  }
}

Creates a new folder in the specified location.

POST/api/v1/servers/{serverId}/files/create-folder

Creates a new folder in the specified location.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Request Body

Parameter	Type	Required	Description
name	string	Yes	The name parameter
path	string	No	The path parameter
name	string	Yes	The name of the folder to create
path	string	No	The parent directory path (defaults to '/')

Example Request

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/files/create-folder" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "name": "example_name",
  "path": "example_path"
}'

Example Response

{
  "success": true,
  "data": {
    "message": "Folder created successfully"
  }
}

Decompresses an archive file.

POST/api/v1/servers/{serverId}/files/decompress

Decompresses an archive file.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Request Body

Parameter	Type	Required	Description
file	string	Yes	The file path
root	string	No	The root parameter
file	string	Yes	The archive file path to decompress
root	string	No	The root directory for the operation (defaults to '/')

Example Request

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/files/decompress" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "file": "example_file",
  "root": "example_root"
}'

Example Response

{
  "success": true,
  "data": {
    "message": "Archive decompressed successfully"
  }
}

Deletes a file or directory from the server.

POST/api/v1/servers/{serverId}/files/delete

Deletes a file or directory from the server.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Request Body

Parameter	Type	Required	Description
file	string	Yes	The file path
file	string	Yes	The file or directory path to delete

Example Request

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/files/delete" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "file": "example_file"
}'

Example Response

{
  "success": true,
  "data": {
    "message": "File deleted successfully"
  }
}

Downloads a file from the server.

GET/api/v1/servers/{serverId}/files/download

Downloads a file from the server.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Query Parameters

Parameter	Type	Required	Description
file	string	Yes	The file path to download

Example Request

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}/files/download" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example Response

{
  "success": true,
  "data": {
    "downloadUrl": "https://..."
  }
}

Returns a list of files and directories in the specified directory.

GET/api/v1/servers/{serverId}/files/list

Returns a list of files and directories in the specified directory.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Query Parameters

Parameter	Type	Required	Description
directory	string	No	The directory path
directory	string	No	The directory path to list (defaults to '/')

Example Request

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}/files/list" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example Response

{
  "success": true,
  "data": {
    "files": [
      {
        "name": "server.properties",
        "size": 1024,
        "isDirectory": false
      },
      {
        "name": "plugins",
        "size": 0,
        "isDirectory": true
      }
    ]
  }
}

Renames or moves a file or directory.

PUT/api/v1/servers/{serverId}/files/rename

Renames or moves a file or directory.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Request Body

Parameter	Type	Required	Description
from	string	Yes	The from parameter
to	string	Yes	The to parameter
from	string	Yes	The source file or directory path
to	string	Yes	The destination file or directory path

Example Request

curl -X PUT "https://www.beaconhosting.org/api/v1/servers/{serverId}/files/rename" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "from": "example_from",
  "to": "example_to"
}'

Example Response

{
  "success": true,
  "data": {
    "message": "File renamed successfully"
  }
}

Initiates a file upload and returns a JWT token for authentication.

POST/api/v1/servers/{serverId}/files/upload

Initiates a file upload and returns a JWT token for authentication.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Query Parameters

Parameter	Type	Required	Description
directory	string	No	The target directory for the upload (defaults to '/')

Example Request

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/files/upload" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json"

Example Response

{
  "success": true,
  "data": {
    "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "uploadUrl": "/api/v1/servers/123/files/upload-direct",
    "instructions": "Use this JWT in the Authorization header..."
  }
}

Writes content to a file, creating it if it doesn't exist.

POST/api/v1/servers/{serverId}/files/write

Writes content to a file, creating it if it doesn't exist.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Request Body

Parameter	Type	Required	Description
file	string	Yes	The file path
content	string	No	The content parameter
file	string	Yes	The file path to write to
content	string	Yes	The content to write to the file

Example Request

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/files/write" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "file": "example_file",
  "content": "example_content"
}'

Example Response

{
  "success": true,
  "data": {
    "message": "File written successfully"
  }
}

Sets a network allocation as the primary allocation for the server.

POST/api/v1/servers/{serverId}/network/allocations/{allocation}/primary

Sets a network allocation as the primary allocation for the server.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server
allocation	string	Yes	The allocation parameter

Example Request

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/network/allocations/{allocation}/primary" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json"

Example Response

{
  "success": true,
  "data": {
    "message": "Primary allocation updated"
  }
}

Updates notes for a specific network allocation.

POST/api/v1/servers/{serverId}/network/allocations/{allocation}

Updates notes for a specific network allocation.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server
allocation	string	Yes	The allocation parameter

Request Body

Parameter	Type	Required	Description
notes	string	No	The notes parameter
notes	string	No	Notes to add to the allocation

Example Request

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/network/allocations/{allocation}" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "notes": "example_notes"
}'

Example Response

{
  "success": true,
  "data": {
    "port": 25565,
    "notes": "Main server port"
  }
}

Removes a network allocation from the server.

DELETE/api/v1/servers/{serverId}/network/allocations/{allocation}

Removes a network allocation from the server.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server
allocation	string	Yes	The allocation parameter

Request Body

Parameter	Type	Required	Description
notes	string	No	The notes parameter

Example Request

curl -X DELETE "https://www.beaconhosting.org/api/v1/servers/{serverId}/network/allocations/{allocation}" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example Response

{
  "success": true,
  "data": {
    "message": "Allocation removed successfully"
  }
}

Returns network allocation details for the specified server.

GET/api/v1/servers/{serverId}/network/allocations

Returns network allocation details for the specified server.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Example Request

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}/network/allocations" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example Response

{
  "success": true,
  "data": {
    "allocations": [
      {
        "id": "alloc-123",
        "ip": "192.168.1.1",
        "port": 25565,
        "primary": true
      }
    ]
  }
}

Adds a new network allocation to the specified server.

POST/api/v1/servers/{serverId}/network/allocations

Adds a new network allocation to the specified server.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Example Request

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/network/allocations" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json"

Example Response

{
  "success": true,
  "data": {
    "message": "Allocation added",
    "allocationId": "alloc-123"
  }
}

Returns the permissions for the authenticated user on the specified server.

GET/api/v1/servers/{serverId}/permissions

Returns the permissions for the authenticated user on the specified server.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Example Request

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}/permissions" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example Response

{
  "success": true,
  "data": {
    "permissions": [
      "console.read",
      "console.write",
      "files.read",
      "files.write"
    ],
    "isOwner": false
  }
}

Returns detailed information about a specific server.

GET/api/v1/servers/{serverId}

Returns detailed information about a specific server.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Request Body

Parameter	Type	Required	Description
action	string	No	The action to perform

Example Request

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example Response

{
  "success": true,
  "data": {
    "id": "servers/123",
    "name": "Minecraft Server",
    "status": "running",
    "resources": {
      "memory": 4096,
      "disk": 30720,
      "cpu": 2
    },
    "createdAt": "2025-04-15T18:30:00Z"
  }
}

Updates the power state of a server (start, stop, restart, kill).

POST/api/v1/servers/{serverId}

Updates the power state of a server (start, stop, restart, kill).

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Request Body

Parameter	Type	Required	Description
action	string	No	The action to perform
action	string	Yes	The power action to perform: "start", "stop", "restart", or "kill"

Example Request

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "action": "restart"
}'

Example Response

{
  "success": true,
  "data": {
    "message": "Server restart initiated"
  }
}

Returns resource limits and usage for the server.

GET/api/v1/servers/{serverId}/settings/resources

Returns resource limits and usage for the server.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Example Request

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}/settings/resources" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example Response

{
  "success": true,
  "data": {
    "databases": {
      "limit": 5,
      "current": 2
    },
    "allocations": {
      "limit": 3,
      "current": 1
    },
    "backups": {
      "limit": 10,
      "current": 3
    },
    "schedules": {
      "limit": 5,
      "current": 1
    },
    "server": {
      "status": "running",
      "name": "Minecraft Server"
    }
  }
}

Returns details about a specific subuser.

GET/api/v1/servers/{serverId}/users/{subuser}

Returns details about a specific subuser.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server
subuser	string	Yes	The subuser parameter

Example Request

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}/users/{subuser}" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example Response

{
  "success": true,
  "data": {
    "id": "user-123",
    "email": "subuser@example.com",
    "permissions": [
      "console.read",
      "files.read"
    ]
  }
}

Updates permissions for a specific subuser.

POST/api/v1/servers/{serverId}/users/{subuser}

Updates permissions for a specific subuser.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server
subuser	string	Yes	The subuser parameter

Request Body

Parameter	Type	Required	Description
permissions	array	Yes	Array of permissions to grant to the subuser

Example Request

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/users/{subuser}" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "permissions": "example_permissions"
}'

Example Response

{
  "success": true,
  "data": {
    "message": "Permissions updated"
  }
}

Removes a subuser from the server.

DELETE/api/v1/servers/{serverId}/users/{subuser}

Removes a subuser from the server.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server
subuser	string	Yes	The subuser parameter

Example Request

curl -X DELETE "https://www.beaconhosting.org/api/v1/servers/{serverId}/users/{subuser}" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example Response

{
  "success": true,
  "data": {
    "message": "Subuser removed successfully"
  }
}

Returns a list of all subusers for the specified server.

GET/api/v1/servers/{serverId}/users

Returns a list of all subusers for the specified server.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Example Request

curl -X GET "https://www.beaconhosting.org/api/v1/servers/{serverId}/users" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "user-123",
      "email": "subuser@example.com",
      "permissions": [
        "console.read",
        "files.read"
      ]
    }
  ]
}

Creates a new subuser for the specified server.

POST/api/v1/servers/{serverId}/users

Creates a new subuser for the specified server.

Path Parameters

Parameter	Type	Required	Description
serverId	string	Yes	The unique identifier of the server

Request Body

Parameter	Type	Required	Description
userEmail	string	Yes	The email address of the user to add as a subuser
permissions	array	Yes	Array of permissions to grant to the subuser

Example Request

curl -X POST "https://www.beaconhosting.org/api/v1/servers/{serverId}/users" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "userEmail": "example_userEmail",
  "permissions": "example_permissions"
}'

Example Response

{
  "success": true,
  "data": {
    "message": "Subuser created",
    "userId": "user-123"
  }
}

Returns a list of all servers associated with your account.

GET/api/v1/servers

Returns a list of all servers associated with your account.

Example Request

curl -X GET "https://www.beaconhosting.org/api/v1/servers" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "servers/123",
      "name": "Minecraft Server",
      "status": "running",
      "memory": 4096,
      "disk": 30720,
      "cpu": 2,
      "createdAt": "2025-04-15T18:30:00Z"
    }
  ]
}

Rate Limiting

To ensure the stability of our service, the API enforces rate limits based on the number of requests per minute. The current rate limits are:

Plan	Rate Limit
Standard	180 requests per minute
Enterprise	For higher limits, please contact support

When the rate limit is exceeded, the API will return a 429 Too Many Requests status code. The response headers include:

Header	Description
X-RateLimit-Limit	The maximum number of requests allowed per minute
X-RateLimit-Remaining	The number of requests remaining in the current minute
X-RateLimit-Reset	The time (in seconds) until the rate limit resets

Support

If you encounter any issues or have questions about using the API, please don't hesitate to reach out:

Documentation Issues

For issues with this documentation or to suggest improvements:

GitHub Issues

API Support

For technical support with the API:

api-support@beaconhosting.org