🔐 Loading authentication...

Nodots Backgammon API v1.0.0

REST API and WebSocket endpoints for the Nodots Backgammon game platform. This API provides complete game management, user authentication, real-time gameplay features, and AI-powered robot opponents.

Getting Started

The Nodots Backgammon API is built using modern REST principles with WebSocket support for real-time game updates. All endpoints return JSON responses with consistent error handling and status codes.

🎯 Game Flow: Create users → Create game with 2 players → Roll for start → Take turns (roll dice, move checkers, confirm turn) → Game completes when a player bears off all checkers.

Authentication

The API uses Auth0 for authentication. Protected endpoints require a Bearer token in the Authorization header. Some endpoints are public (marked with 🌐) while others require authentication (marked with 🔒).

Authentication Header

Authorization: Bearer YOUR_JWT_TOKEN

Base URL

All API endpoints are prefixed with the base URL:

http://localhost:3000/api/v1.0

WebSocket Support

The API includes native WebSocket support for real-time game updates. WebSocket connections provide:

WebSocket Events: game-updated, roll-for-start-completed, dice-rolled, move-made, turn-changed, move-undone, dice-switched, simulation-update

Health

Health Check

🌐GET /health
Terminal - Ready

Description: Check API health and version information.

Response

200 OK Health status object

Users

List Users

🔒GET /users
Terminal - Ready

Description: Retrieve all users with optional filtering by user type.

Query Parameters

Parameter Type Required Description
user_type string No Filter by user type: "human" or "robot"

Response

200 OK Array of user objects
400 Bad Request Invalid user_type parameter
500 Internal Server Error Failed to get users

Get User by ID

🔒GET /users/:userId
Terminal - Ready

Description: Retrieve a specific user by their ID.

Path Parameters

Parameter Type Required Description
userId string Yes Unique user identifier

Response

200 OK User object
404 Not Found User not found
500 Internal Server Error Failed to get user

Lookup User by Source and External ID

🌐GET /users/sub/:source/:externalId
Terminal - Ready

Description: Look up a user by their authentication source and external ID.

Path Parameters

Parameter Type Required Description
source string Yes Authentication source (e.g., "auth0")
externalId string Yes External user identifier

Response

200 OK User object or null if not found

Get User's Active Game

🔒GET /users/:userId/game
Terminal - Ready

Description: Retrieve the active game for a specific user.

Response

200 OK Game object
403 Forbidden Not authorized to access this user's game
404 Not Found No active game found
500 Internal Server Error Failed to get user game

Create or Update User

🌐POST /users
Terminal - Ready

Description: Create a new user or update an existing user's profile.

Request Body

Field Type Required Description
source string Yes Authentication source
externalId string Yes External user ID
email string Yes User email address
given_name string No User's first name
family_name string No User's last name
nickname string No User's nickname
picture string No User's profile picture URL

Response

200 OK User updated
201 Created User created
500 Internal Server Error Failed to create/update user

Update User

🔒PUT /users
Terminal - Ready

Description: Update an existing user's profile information.

Response

200 OK User updated
400 Bad Request Invalid request data
403 Forbidden Not authorized
404 Not Found User not found
500 Internal Server Error Failed to update user

Logout User

🔒POST /users/logout/:userId
Terminal - Ready

Description: Log out a user and update their status.

Response

200 OK User logged out
403 Forbidden Not authorized
404 Not Found User not found
500 Internal Server Error Failed to logout user

User Heartbeat

🔒POST /users/heartbeat/:userId
Terminal - Ready

Description: Update user's last active timestamp.

Response

200 OK Heartbeat updated
403 Forbidden Not authorized
404 Not Found User not found
500 Internal Server Error Failed to update heartbeat

Games

List Games

🌐GET /games
Terminal - Ready

Description: Retrieve all games with enriched board information.

Response

200 OK Array of game objects with ASCII boards
500 Internal Server Error Failed to get games

Get Game

🌐GET /games/:id
Terminal - Ready

Description: Retrieve a specific game by ID with enriched information.

Response

200 OK Game object with ASCII board
404 Not Found Game not found
500 Internal Server Error Failed to get game

Create Game

🌐POST /games
Terminal - Ready

Description: Create a new backgammon game with exactly 2 players.

⚠️ Important: Games MUST be created with exactly 2 players. Both player1.userId and player2.userId are required and must be different.

Request Body

Field Type Required Description
player1.userId string Yes First player's user ID
player1.type string No "human" or "robot" (default: "human")
player1.name string No Player display name
player1.difficulty string No Robot difficulty: "beginner", "intermediate", "advanced"
player2.userId string Yes Second player's user ID
player2.type string No "human" or "robot" (default: "human")
player2.name string No Player display name
player2.difficulty string No Robot difficulty: "beginner", "intermediate", "advanced"

Response

201 Created Game created successfully
400 Bad Request Invalid player configuration
500 Internal Server Error Failed to create game

Update Game

🌐PUT /games/:id
Terminal - Ready

Description: Update an existing game's state.

Response

200 OK Game updated successfully
500 Internal Server Error Failed to update game

Roll for Start

🌐POST /games/:id/roll-for-start
Terminal - Ready

Description: Roll dice to determine which player goes first. Includes automatic robot handling and first move preparation.

Response

200 OK Roll completed, winner determined
400 Bad Request Invalid game state for rolling
404 Not Found Game not found
500 Internal Server Error Failed to roll for start

Roll Dice

🌐POST /games/:id/roll
Terminal - Ready

Description: Roll dice for the active player's turn. Includes automatic robot move processing and WebSocket notifications.

Response

200 OK Dice rolled successfully
400 Bad Request Invalid game state for rolling
404 Not Found Game not found
500 Internal Server Error Failed to roll dice

Switch Dice Order

🌐POST /games/:id/switch-dice
Terminal - Ready

Description: Switch the order of dice for strategic move planning. Only available in 'rolled' game state.

Response

200 OK Dice order switched
400 Bad Request Invalid state for dice switching
404 Not Found Game not found
500 Internal Server Error Failed to switch dice

Move Checker

🌐POST /games/:id/move
Terminal - Ready

Description: Move a checker for the active player. Handles move validation, multiple move options, and game state updates.

Request Body

Field Type Required Description
checkerId string Yes ID of the checker to move

Response

200 OK Move executed successfully
400 Bad Request Invalid move or multiple moves possible
404 Not Found Game not found
500 Internal Server Error Failed to execute move

Undo Move

🌐POST /games/:id/undo-move
Terminal - Ready

Description: Undo the last move in the current turn. Only available to human players in 'moving' or 'moved' states.

Request Body

Field Type Required Description
playerId string Yes ID of the player requesting undo

Response

200 OK Move undone successfully
400 Bad Request Invalid state or player for undo
404 Not Found Game not found
500 Internal Server Error Failed to undo move

Confirm Turn

🌐POST /games/:id/confirm-turn
Terminal - Ready

Description: Confirm the current player's turn and pass control to the next player. Handles turn transitions and robot automation.

Response

200 OK Turn confirmed and passed
400 Bad Request Invalid state for turn confirmation
404 Not Found Game not found
500 Internal Server Error Failed to confirm turn

Get Robot Move Recommendation

🌐POST /games/:id/robot-move
Terminal - Ready

Description: Get AI-powered move recommendation for robot players. Uses GNU Backgammon AI when available, falls back to built-in AI.

🤖 AI Integration: This endpoint integrates with GNU Backgammon for optimal move analysis and includes fallback AI for consistent robot behavior.

Response

200 OK Move recommendation provided
400 Bad Request Not available for current player or state
404 Not Found Game not found
500 Internal Server Error AI processing failed

Set Robot Difficulty

🌐PUT /games/:id/robot-difficulty
Terminal - Ready

Description: Update the difficulty level for robot players in the game.

Request Body

Field Type Required Description
difficulty string Yes "beginner", "intermediate", or "advanced"

Response

200 OK Difficulty updated
400 Bad Request Invalid difficulty level
404 Not Found Game not found
500 Internal Server Error Failed to update difficulty

Game Simulation

The simulation system allows for automated game testing and analysis. Simulations can run at different speeds and be controlled interactively.

Start Simulation

🌐POST /games/:id/simulation/start
Terminal - Ready

Description: Start an automated game simulation with configurable parameters.

Request Body

Field Type Required Description
speed number No Milliseconds between moves (min: 2000, default: 2000)
autoPlay boolean No Enable automatic play (default: true)
players object No Player configuration override

Response

200 OK Simulation started
400 Bad Request Invalid parameters or simulation already running
404 Not Found Game not found
500 Internal Server Error Failed to start simulation

Pause Simulation

🌐POST /games/:id/simulation/pause
Terminal - Ready

Description: Pause a running simulation.

Resume Simulation

🌐POST /games/:id/simulation/resume
Terminal - Ready

Description: Resume a paused simulation.

Stop Simulation

🌐POST /games/:id/simulation/stop
Terminal - Ready

Description: Stop a simulation and optionally save results.

Get Simulation Status

🌐GET /games/:id/simulation/status
Terminal - Ready

Description: Get current simulation status and progress information.

Step Through Simulation

🌐POST /games/:id/simulation/step
Terminal - Ready

Description: Manually step through simulation moves.

Update Simulation Speed

🌐POST /games/:id/simulation/speed
Terminal - Ready

Description: Update the speed of a running simulation.

Boards

Generate Random Board

🌐GET /boards
Terminal - Ready

Description: Generate a random backgammon board configuration in ASCII format.

Response

200 OK ASCII board representation

Get ASCII Board for Game

🌐GET /boards/ascii/:gameId
Terminal - Ready

Description: Get ASCII representation of a specific game's board state.

Response

200 OK ASCII board for the game
404 Not Found Game not found
500 Internal Server Error Database not available

Game History

The history system provides complete game replay and analysis capabilities using functional programming patterns for reliable state reconstruction.

Get Game History

🌐GET /history/games/:gameId
Terminal - Ready

Description: Retrieve the complete history of actions for a game.

Response

200 OK Complete game history with all actions
404 Not Found Game or history not found
500 Internal Server Error Failed to retrieve history

Get Specific Action

🌐GET /history/games/:gameId/actions/:sequenceNumber
Terminal - Ready

Description: Retrieve a specific action by its sequence number.

Response

200 OK Action details
400 Bad Request Invalid sequence number
404 Not Found Game or action not found
500 Internal Server Error Failed to retrieve action

Reconstruct Game State

🌐GET /history/games/:gameId/reconstruct/:sequenceNumber
Terminal - Ready

Description: Reconstruct the game state as it was after a specific action.

Query Parameters

Parameter Type Default Description
validateIntegrity boolean false Perform integrity validation during reconstruction
includeMetadata boolean true Include reconstruction metadata in response

Response

200 OK Reconstructed game state
400 Bad Request Invalid sequence number
404 Not Found Game or sequence not found
422 Unprocessable Entity Integrity validation failed
501 Not Implemented Feature not yet available
500 Internal Server Error Reconstruction failed

Get Action Range

🌐GET /history/games/:gameId/range
Terminal - Ready

Description: Retrieve actions within a specified range of sequence numbers.

Query Parameters

Parameter Type Required Description
start number Yes Starting sequence number (1-based)
end number Yes Ending sequence number (inclusive)

Response

200 OK Array of actions in the range
400 Bad Request Invalid range parameters
404 Not Found Game not found
500 Internal Server Error Failed to retrieve range

Get Latest Action

🌐GET /history/games/:gameId/latest
Terminal - Ready

Description: Retrieve the most recent action in a game's history.

Response

200 OK Latest action details
404 Not Found Game not found or no actions
500 Internal Server Error Failed to retrieve latest action

Export to XG Format

🌐GET /history/games/:gameId/export/xg
Terminal - Ready

Description: Export game history to XG format for external analysis tools.

⚠️ Not Implemented: This feature is planned for future development.

Response

501 Not Implemented Feature not yet available

Analyze Game

🌐POST /history/games/:gameId/analyze
Terminal - Ready

Description: Trigger automated analysis of game moves and strategy.

⚠️ Not Implemented: This feature is planned for future development.

Response

501 Not Implemented Feature not yet available