API Overview

Introduction

The StellarStack API is a RESTful API built with Hono that provides programmatic access to manage your game servers, nodes, blueprints, and more. The API supports JSON request and response formats.

Base URL

The API is available at:

http://localhost:3001

In production environments, this will be your configured API URL set via the API_URL environment variable.

Versioning

The current API uses path-based versioning with all endpoints prefixed with /api. Future versions may introduce version-specific paths like /api/v2 if breaking changes are required.

Response Format

All API responses are returned in JSON format with appropriate HTTP status codes.

Success Response

Successful requests return a 200 OK status code (or 201 Created for resource creation) with the requested data:

{
  "id": "srv_abc123",
  "name": "my-server",
  "status": "running"
}

Error Response

Error responses include an error field with a descriptive message:

{
  "error": "Resource not found"
}

Common Status Codes

200

Request successful

201

Created

Resource created successfully

400

Bad Request

Invalid request parameters or body

401

Unauthorized

Authentication required or invalid credentials

403

Forbidden

Insufficient permissions to access resource

404

Not Found

Resource not found

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Server error occurred

Rate Limit Headers

All API responses include rate limit information in the headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1709308800

X-RateLimit-Limit

string

Maximum number of requests allowed in the current window

X-RateLimit-Remaining

string

Number of requests remaining in the current window

X-RateLimit-Reset

string

Unix timestamp when the rate limit window resets

CORS

The API supports Cross-Origin Resource Sharing (CORS) for requests from the configured frontend URL. In desktop mode, requests from any localhost origin are allowed. Allowed origins are configured via the FRONTEND_URL environment variable.

Health Check

You can check the API health status using the health endpoint:

curl http://localhost:3001/health

Response:

{
  "status": "ok",
  "timestamp": "2026-03-01T12:00:00.000Z"
}

Request Format

All POST and PUT requests should include a Content-Type: application/json header and a JSON request body.

Example Request

curl -X POST http://localhost:3001/api/servers \
  -H "Content-Type: application/json" \
  -H "Cookie: better-auth.session_token=<session_token>" \
  -d '{
    "name": "my-server",
    "nodeId": "node_123",
    "blueprintId": "bp_456"
  }'

Introduction

Endpoints

Introduction

Base URL

Versioning

Response Format

Success Response

Error Response

Common Status Codes

Rate Limit Headers

CORS

Health Check

Request Format

Example Request

Build docs developers (and LLMs) love

Introduction

Endpoints

​Introduction

​Base URL

​Versioning

​Response Format

​Success Response

​Error Response

​Common Status Codes

​Rate Limit Headers

​CORS

​Health Check

​Request Format

​Example Request

Build docs developers (and LLMs) love

Introduction

Base URL

Versioning

Response Format

Success Response

Error Response

Common Status Codes

Rate Limit Headers

CORS

Health Check

Request Format

Example Request