API Endpoints

BadgerPanel provides a comprehensive REST API for managing all aspects of the platform. This page covers the API conventions, response format, pagination, and provides an overview of the major endpoint groups.

Base URL

All API endpoints are prefixed with /api/v1:

https://panel.your-domain.com/api/v1

Request Format

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <token>` (JWT access token or API key)
`Content-Type`	For POST/PUT/PATCH	`application/json`
`Accept`	No	`application/json` (default)

Example Request

bash

curl -X GET "https://panel.your-domain.com/api/v1/servers" \
  -H "Authorization: Bearer bp_your-api-key" \
  -H "Accept: application/json"

Response Format

All API responses follow a consistent JSON structure.

Successful Response (Single Resource)

json

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "My Minecraft Server",
    "status": "running",
    "memory": 2048,
    "cpu": 200,
    "disk": 10240,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T12:45:00Z"
  }
}

Successful Response (List)

json

{
  "data": [
    {
      "id": "a1b2c3d4-...",
      "name": "Server 1"
    },
    {
      "id": "b2c3d4e5-...",
      "name": "Server 2"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 42,
    "total_pages": 2
  }
}

Error Response

json

{
  "error": {
    "code": "not_found",
    "message": "The requested server was not found.",
    "details": {}
  }
}

Validation Error Response

json

{
  "error": {
    "code": "validation_error",
    "message": "The request body contains invalid data.",
    "details": {
      "name": ["Name is required."],
      "memory": ["Memory must be at least 128 MB."]
    }
  }
}

HTTP Status Codes

Code	Meaning	Description
`200`	OK	Successful GET, PUT, PATCH, or DELETE
`201`	Created	Successful POST that created a resource
`204`	No Content	Successful DELETE with no response body
`400`	Bad Request	Malformed request or validation error
`401`	Unauthorized	Missing or invalid authentication
`403`	Forbidden	Authenticated but lacking permission
`404`	Not Found	Resource does not exist
`409`	Conflict	Resource conflict (e.g., duplicate)
`422`	Unprocessable Entity	Validation error with details
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Unexpected server error

Pagination

All list endpoints support pagination via query parameters:

Parameter	Description	Default
`page`	Page number (1-indexed)	`1`
`per_page`	Items per page (max 100)	`25`

bash

# Get page 2 with 50 items per page
curl "https://panel.your-domain.com/api/v1/servers?page=2&per_page=50" \
  -H "Authorization: Bearer bp_your-api-key"

The response includes a meta object with pagination info:

json

{
  "meta": {
    "current_page": 2,
    "per_page": 50,
    "total": 120,
    "total_pages": 3
  }
}

Filtering & Sorting

Many list endpoints support filtering and sorting:

bash

# Filter by status
curl "https://panel.your-domain.com/api/v1/servers?status=running"

# Search by name
curl "https://panel.your-domain.com/api/v1/servers?search=minecraft"

# Sort by creation date (descending)
curl "https://panel.your-domain.com/api/v1/servers?sort=-created_at"

Prefix sort fields with - for descending order
Multiple sort fields can be comma-separated: sort=-created_at,name

Client API Endpoints

These endpoints are available to authenticated users for managing their own resources.

Servers

Method	Endpoint	Description
`GET`	`/api/v1/servers`	List your servers
`GET`	`/api/v1/servers/{id}`	Get server details
`GET`	`/api/v1/servers/{id}/resources`	Get live resource usage
`POST`	`/api/v1/servers/{id}/power`	Send power action (start, stop, restart, kill)
`POST`	`/api/v1/servers/{id}/command`	Send console command

Power Actions

bash

# Start a server
curl -X POST "https://panel.your-domain.com/api/v1/servers/{id}/power" \
  -H "Authorization: Bearer bp_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"action": "start"}'

Valid actions: start, stop, restart, kill

Send Console Command

bash

curl -X POST "https://panel.your-domain.com/api/v1/servers/{id}/command" \
  -H "Authorization: Bearer bp_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"command": "say Hello from the API!"}'

Files

Method	Endpoint	Description
`GET`	`/api/v1/servers/{id}/files/list`	List directory contents
`GET`	`/api/v1/servers/{id}/files/contents`	Get file contents
`PUT`	`/api/v1/servers/{id}/files/write`	Write/update a file
`POST`	`/api/v1/servers/{id}/files/create-directory`	Create a directory
`POST`	`/api/v1/servers/{id}/files/rename`	Rename a file or directory
`POST`	`/api/v1/servers/{id}/files/copy`	Copy a file
`POST`	`/api/v1/servers/{id}/files/delete`	Delete files

bash

# List files in the root directory
curl "https://panel.your-domain.com/api/v1/servers/{id}/files/list?directory=/" \
  -H "Authorization: Bearer bp_your-api-key"

Databases

Method	Endpoint	Description
`GET`	`/api/v1/servers/{id}/databases`	List server databases
`POST`	`/api/v1/servers/{id}/databases`	Create a database
`DELETE`	`/api/v1/servers/{id}/databases/{db-id}`	Delete a database
`POST`	`/api/v1/servers/{id}/databases/{db-id}/rotate-password`	Rotate password

Backups

Method	Endpoint	Description
`GET`	`/api/v1/servers/{id}/backups`	List backups
`POST`	`/api/v1/servers/{id}/backups`	Create a backup
`GET`	`/api/v1/servers/{id}/backups/{backup-id}/download`	Download a backup
`POST`	`/api/v1/servers/{id}/backups/{backup-id}/restore`	Restore a backup
`DELETE`	`/api/v1/servers/{id}/backups/{backup-id}`	Delete a backup
`POST`	`/api/v1/servers/{id}/backups/{backup-id}/lock`	Lock/unlock a backup

Schedules

Method	Endpoint	Description
`GET`	`/api/v1/servers/{id}/schedules`	List schedules
`POST`	`/api/v1/servers/{id}/schedules`	Create a schedule
`PUT`	`/api/v1/servers/{id}/schedules/{schedule-id}`	Update a schedule
`DELETE`	`/api/v1/servers/{id}/schedules/{schedule-id}`	Delete a schedule
`POST`	`/api/v1/servers/{id}/schedules/{schedule-id}/execute`	Execute now

Subusers

Method	Endpoint	Description
`GET`	`/api/v1/servers/{id}/subusers`	List subusers
`POST`	`/api/v1/servers/{id}/subusers`	Invite a subuser
`PUT`	`/api/v1/servers/{id}/subusers/{subuser-id}`	Update permissions
`DELETE`	`/api/v1/servers/{id}/subusers/{subuser-id}`	Remove a subuser

Account

Method	Endpoint	Description
`GET`	`/api/v1/account`	Get account details
`PUT`	`/api/v1/account`	Update profile
`PUT`	`/api/v1/account/password`	Change password
`GET`	`/api/v1/account/api-keys`	List API keys
`POST`	`/api/v1/account/api-keys`	Create an API key
`DELETE`	`/api/v1/account/api-keys/{key-id}`	Delete an API key
`GET`	`/api/v1/account/sessions`	List active sessions
`DELETE`	`/api/v1/account/sessions/{session-id}`	Revoke a session

Billing (Client)

Method	Endpoint	Description
`GET`	`/api/v1/store/products`	List available products
`GET`	`/api/v1/store/products/{id}`	Get product details
`GET`	`/api/v1/store/cart`	Get shopping cart
`POST`	`/api/v1/store/cart`	Add item to cart
`DELETE`	`/api/v1/store/cart/{item-id}`	Remove cart item
`POST`	`/api/v1/store/checkout`	Process checkout
`POST`	`/api/v1/store/coupon`	Apply coupon code
`GET`	`/api/v1/billing/invoices`	List your invoices
`GET`	`/api/v1/billing/invoices/{id}`	Get invoice details
`GET`	`/api/v1/billing/services`	List your services
`GET`	`/api/v1/billing/credits`	Get credit balance

Admin API Endpoints

These endpoints require admin permissions (accessible to users with the appropriate role).

Admin: Servers

Method	Endpoint	Description
`GET`	`/api/v1/admin/servers`	List all servers
`POST`	`/api/v1/admin/servers`	Create a server
`GET`	`/api/v1/admin/servers/{id}`	Get server details
`PUT`	`/api/v1/admin/servers/{id}`	Update server
`DELETE`	`/api/v1/admin/servers/{id}`	Delete a server
`POST`	`/api/v1/admin/servers/{id}/suspend`	Suspend a server
`POST`	`/api/v1/admin/servers/{id}/unsuspend`	Unsuspend a server
`POST`	`/api/v1/admin/servers/{id}/reinstall`	Reinstall a server
`POST`	`/api/v1/admin/servers/{id}/transfer`	Migrate a server

Create a Server

bash

curl -X POST "https://panel.your-domain.com/api/v1/admin/servers" \
  -H "Authorization: Bearer bp_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Server",
    "user_id": "user-uuid",
    "node_id": "node-uuid",
    "egg_id": "egg-uuid",
    "allocation_id": "allocation-uuid",
    "memory": 2048,
    "cpu": 200,
    "disk": 10240,
    "swap": 0,
    "io": 500,
    "databases_limit": 2,
    "backups_limit": 3,
    "allocations_limit": 1
  }'

Admin: Users

Method	Endpoint	Description
`GET`	`/api/v1/admin/users`	List all users
`POST`	`/api/v1/admin/users`	Create a user
`GET`	`/api/v1/admin/users/{id}`	Get user details
`PUT`	`/api/v1/admin/users/{id}`	Update user
`DELETE`	`/api/v1/admin/users/{id}`	Delete user

Admin: Nodes

Method	Endpoint	Description
`GET`	`/api/v1/admin/nodes`	List all nodes
`POST`	`/api/v1/admin/nodes`	Create a node
`GET`	`/api/v1/admin/nodes/{id}`	Get node details
`PUT`	`/api/v1/admin/nodes/{id}`	Update a node
`DELETE`	`/api/v1/admin/nodes/{id}`	Delete a node
`GET`	`/api/v1/admin/nodes/{id}/allocations`	List allocations
`POST`	`/api/v1/admin/nodes/{id}/allocations`	Create allocations
`DELETE`	`/api/v1/admin/nodes/{id}/allocations/{alloc-id}`	Delete allocation

Admin: Nests & Eggs

Method	Endpoint	Description
`GET`	`/api/v1/admin/nests`	List nests
`POST`	`/api/v1/admin/nests`	Create a nest
`GET`	`/api/v1/admin/nests/{id}`	Get nest details
`GET`	`/api/v1/admin/nests/{id}/eggs`	List eggs in a nest
`POST`	`/api/v1/admin/nests/{id}/eggs`	Create an egg
`GET`	`/api/v1/admin/eggs/{id}`	Get egg details
`PUT`	`/api/v1/admin/eggs/{id}`	Update an egg
`POST`	`/api/v1/admin/eggs/import`	Import egg from JSON
`GET`	`/api/v1/admin/eggs/{id}/export`	Export egg as JSON

Admin: Billing

Method	Endpoint	Description
`GET`	`/api/v1/admin/billing/products`	List products
`POST`	`/api/v1/admin/billing/products`	Create a product
`PUT`	`/api/v1/admin/billing/products/{id}`	Update a product
`DELETE`	`/api/v1/admin/billing/products/{id}`	Delete a product
`GET`	`/api/v1/admin/billing/orders`	List all orders
`GET`	`/api/v1/admin/billing/invoices`	List all invoices
`GET`	`/api/v1/admin/billing/services`	List all services
`GET`	`/api/v1/admin/billing/coupons`	List coupons
`POST`	`/api/v1/admin/billing/coupons`	Create a coupon

Admin: Roles

Method	Endpoint	Description
`GET`	`/api/v1/admin/roles`	List roles
`POST`	`/api/v1/admin/roles`	Create a role
`PUT`	`/api/v1/admin/roles/{id}`	Update a role
`DELETE`	`/api/v1/admin/roles/{id}`	Delete a role

Admin: Settings

Method	Endpoint	Description
`GET`	`/api/v1/admin/settings`	Get all settings
`PUT`	`/api/v1/admin/settings`	Update settings
`POST`	`/api/v1/admin/settings/email/test`	Send test email

WebSocket Endpoints

Real-time features use WebSocket connections.

Server Console

wss://panel.your-domain.com/api/v1/servers/{id}/ws

Connect via WebSocket to receive real-time console output and send commands:

javascript

const ws = new WebSocket(
  'wss://panel.your-domain.com/api/v1/servers/{id}/ws',
  { headers: { 'Authorization': 'Bearer your-token' } }
);

// Receive console output
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'console_output') {
    console.log(data.message);
  }
  if (data.type === 'stats') {
    console.log('CPU:', data.cpu, 'Memory:', data.memory);
  }
  if (data.type === 'status') {
    console.log('Server status:', data.status);
  }
};

// Send a command
ws.send(JSON.stringify({
  type: 'command',
  command: 'say Hello from WebSocket!'
}));

// Send a power action
ws.send(JSON.stringify({
  type: 'power',
  action: 'restart'
}));

WebSocket Message Types (Received):

Type	Description
`console_output`	Line of console output from the server
`stats`	Resource usage update (CPU, memory, disk, network)
`status`	Server status change (starting, running, stopping, offline)
`install_output`	Installation progress output

WebSocket Message Types (Sent):

Type	Description
`command`	Send a command to the server console
`power`	Send a power action (start, stop, restart, kill)

Error Handling

Common Error Codes

Code	HTTP Status	Description
`unauthorized`	401	Authentication required or token expired
`forbidden`	403	Insufficient permissions
`not_found`	404	Resource does not exist
`validation_error`	422	Request body failed validation
`rate_limit_exceeded`	429	Too many requests
`internal_error`	500	Unexpected server error
`server_offline`	409	Server is not running (for console/command)
`server_locked`	409	Server is locked by another operation

Error Handling Example

python

import requests

response = requests.get(
    "https://panel.your-domain.com/api/v1/servers/invalid-id",
    headers={"Authorization": "Bearer bp_your-api-key"}
)

if response.status_code == 200:
    server = response.json()["data"]
elif response.status_code == 401:
    print("Authentication failed - check your API key")
elif response.status_code == 403:
    print("Permission denied")
elif response.status_code == 404:
    print("Server not found")
elif response.status_code == 429:
    retry_after = response.headers.get("Retry-After", 60)
    print(f"Rate limited - retry after {retry_after} seconds")
else:
    error = response.json().get("error", {})
    print(f"Error: {error.get('message', 'Unknown error')}")

Next Steps

Authentication -- Authentication methods and rate limiting
Configuration -- API configuration options

API Endpoints ​

Base URL ​

Request Format ​

Headers ​

Example Request ​

Response Format ​

Successful Response (Single Resource) ​

Successful Response (List) ​

Error Response ​

Validation Error Response ​

HTTP Status Codes ​

Pagination ​

Filtering & Sorting ​

Client API Endpoints ​

Servers ​

Power Actions ​

Send Console Command ​

Files ​

Databases ​

Backups ​

Schedules ​

Subusers ​

Account ​

Billing (Client) ​

Admin API Endpoints ​

Admin: Servers ​

Create a Server ​

Admin: Users ​

Admin: Nodes ​

Admin: Nests & Eggs ​

Admin: Billing ​

Admin: Roles ​

Admin: Settings ​

WebSocket Endpoints ​

Server Console ​

Error Handling ​

Common Error Codes ​

Error Handling Example ​

Next Steps ​

API Endpoints

Base URL

Request Format

Headers

Example Request

Response Format

Successful Response (Single Resource)

Successful Response (List)

Error Response

Validation Error Response

HTTP Status Codes

Pagination

Filtering & Sorting

Client API Endpoints

Servers

Power Actions

Send Console Command

Files

Databases

Backups

Schedules

Subusers

Account

Billing (Client)

Admin API Endpoints

Admin: Servers

Create a Server

Admin: Users

Admin: Nodes

Admin: Nests & Eggs

Admin: Billing

Admin: Roles

Admin: Settings

WebSocket Endpoints

Server Console

Error Handling

Common Error Codes

Error Handling Example

Next Steps