Ludo API Documentation — Complete Reference

This is the authoritative reference for integrating with the LudoKingAPI platform. It covers authentication schemes, all REST endpoints with their request and response schemas, WebSocket event types, rate limiting policies, and error codes. Every endpoint includes a working cURL example you can paste directly into your terminal.

Base URL and Versioning

The API is versioned via URL path. The current stable version is v1. All requests should target the following base URL:

https://api.ludokingapi.site/v1

Authentication

The API uses Bearer token authentication. Obtain your API key from the dashboard. Pass the key in the Authorization header of every request. Keys are scoped to an application and can be rotated without downtime.

curl -X GET "https://api.ludokingapi.site/v1/rooms" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Rate Limiting

Rate limits are enforced per API key and vary by endpoint tier. Free tier requests are limited to 100 per minute. Paid tiers range from 500 to 10,000 requests per minute. Rate limit headers are included in every response:

X-RateLimit-Limit — Maximum requests per window
X-RateLimit-Remaining — Requests remaining in current window
X-RateLimit-Reset — Unix timestamp when the window resets

When you exceed the limit, the API returns 429 Too Many Requests. Implement exponential backoff with jitter in your client to handle this gracefully.

REST Endpoints

Players

POST /players Register a new player and receive a session token

Request body:

{
  "playerName": "ArjunK",
  "deviceId": "device-uuid-123",
  "platform": "android"
}

Success response (201 Created):

{
  "success": true,
  "data": {
    "playerId": "plr_a1b2c3d4",
    "playerName": "ArjunK",
    "sessionToken": "eyJhbGciOiJIUzI1NiJ9...",
    "createdAt": "2026-03-21T10:00:00Z"
  }
}

GET /players/{playerId} Fetch player profile and statistics

Success response (200 OK):

{
  "success": true,
  "data": {
    "playerId": "plr_a1b2c3d4",
    "playerName": "ArjunK",
    "gamesPlayed": 247,
    "gamesWon": 89,
    "winRate": 36.0,
    "currentStreak": 3,
    "rank": "Silver",
    "createdAt": "2025-11-01T08:00:00Z"
  }
}

Rooms

POST /rooms Create a new private game room and get its code

Request body:

{
  "maxPlayers": 4,
  "gameMode": "classic",
  "entryStake": 0,
  "turnTimeLimit": 30
}

GET /rooms/{code} Get room details by room code

POST /rooms/{code}/join Join an existing room

Games

GET /games/{gameId}/state Get the current state of a game in progress

POST /games/{gameId}/move Submit a move (piece selection and target position)

GET /games/{gameId}/history Get the move history of a completed game

Error Codes

All errors follow a consistent JSON envelope:

{
  "success": false,
  "error": {
    "code": "ROOM_FULL",
    "message": "The room has reached its maximum player capacity.",
    "httpStatus": 400
  }
}

Error Code	HTTP Status	Description
`INVALID_API_KEY`	401	API key is missing, expired, or invalid
`ROOM_NOT_FOUND`	404	Room code does not exist or has expired
`ROOM_FULL`	400	Room has reached maximum player capacity
`GAME_IN_PROGRESS`	400	Cannot join — game has already started
`INVALID_MOVE`	400	The submitted move violates game rules
`NOT_YOUR_TURN`	403	Attempted to act out of turn
`RATE_LIMITED`	429	Too many requests — back off and retry

WebSocket Events

Real-time game events are delivered over a WebSocket connection at wss://api.ludokingapi.site/ws. Authenticate by passing your token as a query parameter or in the auth handshake object.

const socket = io("wss://api.ludokingapi.site/ws", {
  auth: { token: "YOUR_SESSION_TOKEN" }
});

socket.on("connect", () => console.log("Connected:", socket.id));

// Client → Server events
socket.emit("room:join", { roomCode: "ABCD12" });
socket.emit("game:roll-dice", { roomCode: "ABCD12" });
socket.emit("game:move-piece", { roomCode: "ABCD12", pieceId: "red_1", targetPosition: 5 });

// Server → Client events
socket.on("room:joined", (data) => { /* handle room join */ });
socket.on("game:dice-rolled", (data) => { /* handle dice roll */ });
socket.on("game:piece-moved", (data) => { /* handle piece move */ });
socket.on("game:turn-change", (data) => { /* handle turn change */ });
socket.on("game:ended", (data) => { /* handle game end */ });
socket.on("room:player-left", (data) => { /* handle player leave */ });

API Note: The LudoKingAPI platform provides a comprehensive, documented REST and WebSocket API for building Ludo game integrations. This documentation describes the standard API reference. For integrating with the official Ludo King mobile game by Gametion, there is no public API — refer to the unofficial API alternatives page for responsible options.

Frequently Asked Questions

How do I get an API key?

What is the response time (latency) SLA for the API?

Does the API support webhooks?

Can I test the API without a paid plan?

How do I handle API versioning?

Start Integrating with the Ludo API

Get your API key and start building in minutes. Full documentation, SDKs, and example projects available.

Chat on WhatsApp