API Documentation

REST API reference for programmatic control of indiekku game servers.

Base URL

http://localhost:3000/api/v1

Authentication

All API endpoints (except /health) require authentication using an API key.

API Key

The API key is automatically generated when you first run indiekku serve. Include it in the Authorization header as a Bearer token.

Authorization: Bearer YOUR_API_KEY

Endpoints

Health Check

Check if the API server is running. No authentication required.

GET /health

Response (200 OK)

{
  "status": "ok"
}

Start Server

Start a new game server instance.

POST /api/v1/servers/start

Request Body

{
  "port": "7777 (optional, auto-assigned if not provided)"
}

Response (201 Created)

{
  "name": "legendary-sword",
  "port": "7777",
  "message": "Game server started successfully"
}

Example

curl -X POST http://localhost:3000/api/v1/servers/start \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port": "7777"}'

List Servers

Get a list of all running game servers.

GET /api/v1/servers

Response (200 OK)

{
  "servers": [
    {
      "name": "legendary-sword",
      "port": "7777",
      "player_count": 0,
      "uptime": "2h 15m",
      "started_at": "2024-01-15T10:30:00Z"
    }
  ],
  "count": 1
}

Example

curl http://localhost:3000/api/v1/servers \
  -H "Authorization: Bearer YOUR_API_KEY"

Stop Server

Stop a running game server.

DELETE /api/v1/servers/:name

Parameters

:name - Server name (e.g., legendary-sword, crimson-dragon)

Response (200 OK)

{
  "message": "Server legendary-sword stopped successfully"
}

Example

curl -X DELETE http://localhost:3000/api/v1/servers/legendary-sword \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Server History

Get history of server events (start/stop).

GET /api/v1/history/servers

Parameters

container - Filter by container name (optional query parameter)

Response (200 OK)

{
  "events": [
    {
      "container": "legendary-sword",
      "event": "started",
      "timestamp": "2024-01-15T10:30:00Z"
    }
  ]
}

Example

curl http://localhost:3000/api/v1/history/servers \
  -H "Authorization: Bearer YOUR_API_KEY"

curl http://localhost:3000/api/v1/history/servers?container=legendary-sword \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Upload History

Get history of server build uploads.

GET /api/v1/history/uploads

Response (200 OK)

{
  "uploads": [
    {
      "filename": "server-build.zip",
      "status": "success",
      "timestamp": "2024-01-15T10:00:00Z"
    }
  ]
}

Example

curl http://localhost:3000/api/v1/history/uploads \
  -H "Authorization: Bearer YOUR_API_KEY"

Heartbeat

Update player count for a running server.

POST /api/v1/heartbeat

Request Body

{
  "name": "legendary-sword",
  "player_count": 4
}

Response (200 OK)

{
  "message": "Heartbeat received"
}

Upload Release

Upload a new server build (ZIP file).

POST /api/v1/upload

Request Body

Content-Type: multipart/form-data
Field name: server_build
File type: .zip

Example

curl -X POST http://localhost:3000/api/v1/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "server_build=@server.zip"

Error Responses

All endpoints may return the following error responses:

400 Bad Request

Invalid request body or parameters.

{
  "error": "Invalid request body"
}

401 Unauthorized

Missing or invalid API key.

{
  "error": "Unauthorized"
}

404 Not Found

Server or resource not found.

{
  "error": "Server not found: legendary-sword"
}

409 Conflict

Port already in use.

{
  "error": "Port 7777 is already in use"
}

500 Internal Server Error

Server-side error.

{
  "error": "Failed to start container: ..."
}

Example Workflow

# 1. Check API health
curl http://localhost:3000/health

# 2. Start a server
curl -X POST http://localhost:3000/api/v1/servers/start \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port": "7777"}'

# 3. List running servers
curl http://localhost:3000/api/v1/servers \
  -H "Authorization: Bearer YOUR_API_KEY"

# 4. Stop the server (use the name from step 3)
curl -X DELETE http://localhost:3000/api/v1/servers/legendary-sword \
  -H "Authorization: Bearer YOUR_API_KEY"

Need help? Check out the CLI documentation or the GitHub repository.