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

List Servers

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"
  },
  {
    "id": "servers/456",
    "name": "Rust Server",
    "status": "stopped",
    "memory": 8192,
    "disk": 61440,
    "cpu": 4,
    "createdAt": "2025-06-20T14:15:00Z"
  }
]
}

Get Server Details

GET /api/v1/servers/{serverId}

Returns detailed information about a specific server.

Path Parameters

Parameter	Type	Description
serverId	string	The unique identifier of the server

Example Request

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

Example Response

{
"success": true,
"data": {
  "id": "servers/123",
  "name": "Minecraft Server",
  "description": "SMP Minecraft server for friends",
  "status": "running",
  "resources": {
    "memory": 4096,
    "disk": 30720,
    "cpu": 2
  },
  "node": "us-west-1",
  "allocations": [
    {
      "id": "allocations/789",
      "ip": "192.168.1.1",
      "port": 25565,
      "notes": "Main port",
      "primary": true
    }
  ],
  "settings": {
    "meta": {
      "name": "Minecraft Server",
      "description": "SMP Minecraft server for friends"
    },
    "limits": {
      "memory": 4096,
      "disk": 30720,
      "cpu": 2
    }
  },
  "createdAt": "2025-04-15T18:30:00Z",
  "updatedAt": "2025-07-01T09:45:00Z"
}
}

Update Server Power State

POST /api/v1/servers/{serverId}

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

Path Parameters

Parameter	Type	Description
serverId	string	The unique identifier of the server

Request Body

Parameter	Type	Required	Description
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/123" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "action": "restart"
}'

Example Response

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

Console

Get Console Logs

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

Retrieves recent console logs from the server.

Path Parameters

Parameter	Type	Description
serverId	string	The unique identifier of the server

Query Parameters

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

Example Request

curl -X GET "https://www.beaconhosting.org/api/v1/servers/123/console?lines=50" \
-H "Authorization: Bearer YOUR_TOKEN_HERE"

Example Response

{
"success": true,
"data": {
  "logs": [
    {
      "timestamp": "2025-07-03T14:30:15Z",
      "level": "INFO",
      "message": "Server started successfully"
    },
    {
      "timestamp": "2025-07-03T14:30:20Z",
      "level": "INFO", 
      "message": "Loading world: world"
    },
    {
      "timestamp": "2025-07-03T14:30:25Z",
      "level": "INFO",
      "message": "Done (5.2s)! For help, type \"help\""
    }
  ],
  "totalLines": 156
}
}

Send Console Command

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

Sends a command to the server console for execution.

Path Parameters

Parameter	Type	Description
serverId	string	The unique identifier of the server

Request Body

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

Example Request

curl -X POST "https://www.beaconhosting.org/api/v1/servers/123/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 sent successfully",
  "command": "say Hello from the API!",
  "timestamp": "2025-07-03T14:35:00Z"
}
}

Databases

List Databases

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

Returns a list of all databases associated with the server.

Path Parameters

Parameter	Type	Description
serverId	string	The unique identifier of the server

Example Request

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

Example Response

{
"success": true,
"data": [
  {
    "id": "db_minecraft_main",
    "name": "minecraft_main", 
    "username": "s123_main",
    "host": "mysql.beaconhosting.org",
    "port": 3306,
    "maxConnections": 10,
    "createdAt": "2025-06-15T10:30:00Z"
  },
  {
    "id": "db_minecraft_logs",
    "name": "minecraft_logs",
    "username": "s123_logs", 
    "host": "
  },
  {
    "id": "db_minecraft_logs",
    "name": "minecraft_logs",
    "username": "s123_logs",
    "host": "mysql.beaconhosting.org",
    "port": 3306,
    "maxConnections": 5,
    "createdAt": "2025-06-20T14:15:00Z"
  }
]
}

Create Database

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

Creates a new database for the server.

Path Parameters

Parameter	Type	Description
serverId	string	The unique identifier of the server

Request Body

Parameter	Type	Required	Description
name	string	Yes	Name for the database (alphanumeric and underscores only)
remote	string	No	Remote access host (default: localhost only)

Example Request

curl -X POST "https://www.beaconhosting.org/api/v1/servers/123/databases" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-H "Content-Type: application/json" \
-d '{
  "name": "player_data",
  "remote": "%"
}'

Example Response

{
"success": true,
"data": {
  "id": "db_player_data",
  "name": "s123_player_data",
  "username": "s123_playerdata",
  "password": "generated_secure_password_123",
  "host": "mysql.beaconhosting.org",
  "port": 3306,
  "connectionString": "mysql://s123_playerdata:generated_secure_password_123@mysql.beaconhosting.org:3306/s123_player_data"
}
}

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