API Reference
API Reference
Complete API documentation for StellarStack
API Reference
StellarStack provides a RESTful API for programmatic access to all features.
Base URL
https://your-domain.com/api/v1Authentication
All API requests require authentication via Bearer token or session cookie.
Bearer Token
curl https://api.example.com/api/v1/servers \
-H "Authorization: Bearer <your-api-token>"Session Cookie
When using the web interface, authentication is handled via HTTP-only cookies.
Response Format
All responses are JSON:
{
"data": { ... },
"meta": {
"total": 100,
"page": 1,
"limit": 20
}
}Error Responses
{
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or expired token",
"details": {}
}
}HTTP Status Codes
| Code | Description |
|---|---|
200 | Success |
201 | Created |
204 | No Content |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not Found |
422 | Validation Error |
429 | Rate Limited |
500 | Server Error |
Rate Limiting
API requests are rate limited:
| Endpoint | Limit |
|---|---|
| General | 60/minute |
| Auth | 10/minute |
| Admin | 30/minute |
Rate limit headers:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1699876543Pagination
List endpoints support pagination:
curl "https://api.example.com/api/v1/servers?page=2&limit=20"| Parameter | Default | Max |
|---|---|---|
page | 1 | - |
limit | 20 | 100 |
API Endpoints
Authentication
| Method | Endpoint | Description |
|---|---|---|
| POST | /auth/signin | Sign in |
| POST | /auth/signup | Sign up |
| POST | /auth/signout | Sign out |
| GET | /auth/session | Get session |
Users
| Method | Endpoint | Description |
|---|---|---|
| GET | /users/me | Get current user |
| PATCH | /users/me | Update current user |
Servers
| Method | Endpoint | Description |
|---|---|---|
| GET | /servers | List servers |
| POST | /servers | Create server |
| GET | /servers/:id | Get server |
| PATCH | /servers/:id | Update server |
| DELETE | /servers/:id | Delete server |
| POST | /servers/:id/start | Start server |
| POST | /servers/:id/stop | Stop server |
| POST | /servers/:id/restart | Restart server |
| POST | /servers/:id/kill | Kill server |
| GET | /servers/:id/console-token | Get console token |
Nodes
| Method | Endpoint | Description |
|---|---|---|
| GET | /nodes | List nodes (admin) |
| POST | /nodes | Register node |
| GET | /nodes/:id | Get node details |
| DELETE | /nodes/:id | Remove node |
| GET | /nodes/:id/stats | Get node stats |
Blueprints
| Method | Endpoint | Description |
|---|---|---|
| GET | /blueprints | List blueprints |
| GET | /blueprints/:id | Get blueprint |
Admin
| Method | Endpoint | Description |
|---|---|---|
| GET | /admin/users | List users |
| GET | /admin/stats | Platform stats |
| POST | /admin/nodes/:id/token | Generate node token |
WebSocket
Real-time console access uses WebSocket:
const ws = new WebSocket('wss://node.example.com:5000/console');
ws.send(JSON.stringify({
type: 'auth',
token: 'strk_console_xxxxx'
}));
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log(data.type, data.data);
};SDK Examples
JavaScript/TypeScript
const response = await fetch('https://api.example.com/api/v1/servers', {
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json',
},
});
const { data } = await response.json();cURL
# List servers
curl https://api.example.com/api/v1/servers \
-H "Authorization: Bearer $TOKEN"
# Create server
curl -X POST https://api.example.com/api/v1/servers \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "My Server",
"nodeId": "node_xxxxx",
"blueprintId": "minecraft-java",
"memory": 2048,
"cpu": 100,
"disk": 10240
}'Python
import requests
headers = {
'Authorization': f'Bearer {token}',
'Content-Type': 'application/json',
}
response = requests.get(
'https://api.example.com/api/v1/servers',
headers=headers
)
data = response.json()