StellarStack
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/v1

Authentication

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>"

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

CodeDescription
200Success
201Created
204No Content
400Bad Request
401Unauthorized
403Forbidden
404Not Found
422Validation Error
429Rate Limited
500Server Error

Rate Limiting

API requests are rate limited:

EndpointLimit
General60/minute
Auth10/minute
Admin30/minute

Rate limit headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1699876543

Pagination

List endpoints support pagination:

curl "https://api.example.com/api/v1/servers?page=2&limit=20"
ParameterDefaultMax
page1-
limit20100

API Endpoints

Authentication

MethodEndpointDescription
POST/auth/signinSign in
POST/auth/signupSign up
POST/auth/signoutSign out
GET/auth/sessionGet session

Users

MethodEndpointDescription
GET/users/meGet current user
PATCH/users/meUpdate current user

Servers

MethodEndpointDescription
GET/serversList servers
POST/serversCreate server
GET/servers/:idGet server
PATCH/servers/:idUpdate server
DELETE/servers/:idDelete server
POST/servers/:id/startStart server
POST/servers/:id/stopStop server
POST/servers/:id/restartRestart server
POST/servers/:id/killKill server
GET/servers/:id/console-tokenGet console token

Nodes

MethodEndpointDescription
GET/nodesList nodes (admin)
POST/nodesRegister node
GET/nodes/:idGet node details
DELETE/nodes/:idRemove node
GET/nodes/:id/statsGet node stats

Blueprints

MethodEndpointDescription
GET/blueprintsList blueprints
GET/blueprints/:idGet blueprint

Admin

MethodEndpointDescription
GET/admin/usersList users
GET/admin/statsPlatform stats
POST/admin/nodes/:id/tokenGenerate 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()