API Documentation

Welcome to the TZ LUDO API documentation! This guide provides everything you need to create and manage Ludo and Snake & Ladders multiplayer games using our REST API. Get started with our powerful endpoints to build exciting gaming experiences.

Authentication

All API requests require an api_key, which you can obtain by signing up on our MY API. Include the API key in the request body for authentication.

Ludo Endpoints

GET/POST https://ludo.tzsmm.com/api/create-game

Create a New Ludo Game

Creates a new Ludo game with two players (red and yellow), each with four tokens. Deducts the match price from the user’s balance.

Request Parameters

Parameter Type Description Required
api_key String Your unique API key for authentication. Yes
match_title Text Optional title to show at top of match. No
callback_url URL Optional URL to receive game updates. No
lose_url URL Optional URL to redirect players on game loss. Defaults to game.lose route. No
win_url URL Optional URL to redirect players on game win. Defaults to game.win route. No
home_url URL Optional URL to redirect players on game cancel. Defaults to game.win route. No
end_time Date Optional game end time. Defaults to 24 hours from creation. No

Example Request (cURL)

curl -X POST https://ludo.tzsmm.com/api/games/create \
-H "Content-Type: application/json" \
-d '{
    "api_key": "your_api_key",
    "callback_url": "https://yourapp.com/callback",
    "lose_url": "https://yourapp.com/lose",
    "win_url": "https://yourapp.com/win",
    "end_time": "2025-04-14T12:00:00Z"
}'

Example Request (Python)

import requests

url = "https://ludo.tzsmm.com/api/games/create"
data = {
    "api_key": "your_api_key",
    "callback_url": "https://yourapp.com/callback",
    "lose_url": "https://yourapp.com/lose",
    "win_url": "https://yourapp.com/win",
    "end_time": "2025-04-14T12:00:00Z"
}
response = requests.post(url, json=data)
print(response.json())

Example Response (Success)

{
    "status": true,
    "message": "Match Created Successfully",
    "game_id": 1,
    "red_id": 1,
    "yellow_id": 2,
    "red_url": "https://ludo.tzsmm.com/game/join/1/red_key_123",
    "yellow_url": "https://ludo.tzsmm.com/game/join/1/yellow_key_456"
}

Error Responses

Status Message Description
false Must Provide API key Missing or invalid API key.
false Invalid API key API key does not match any user.
false Insufficient Balance to Create The Game User’s balance is less than the match price (default: 10).
GET/POST https://ludo.tzsmm.com/api/games/status

Check Ludo Game Status

Retrieves the status and details of a specific Ludo game created by the authenticated user.

Request Parameters

Parameter Type Description Required
api_key String Your unique API key for authentication. Yes
game_id Integer The ID of the game to check. Yes

Example Request (cURL)

curl -X GET "https://ludo.tzsmm.com/api/games/status?api_key=your_api_key&game_id=1"

Example Request (JavaScript)

fetch('https://ludo.tzsmm.com/api/games/status?api_key=your_api_key&game_id=1')
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Error:', error));

Example Response (Success)

{
    "status": true,
    "game_id": 1,
    "winner": null,
    "game_status": "waiting",
    "message": "Game Detailed fetched"
}

Error Responses

Status Message Description
false Must Provide API key and Game ID Missing or invalid parameters.
false Invalid API key API key does not match any user.
false Game Not Found Game ID does not exist or does not belong to the user.

Snake & Ladders Endpoints

GET/POST http://ludo.tzsmm.com/api/snake-create-game

Create a New Snake & Ladders Game

Creates a new Snake & Ladders game with two players (player 1 and player 2). Deducts the match price from the user’s balance.

Request Parameters

Parameter Type Description Required
api_key String Your unique API key for authentication. Yes
match_title Text Optional title to show at top of match. No
callback_url URL Optional URL to receive game updates. No
lose_url URL Optional URL to redirect players on game loss. No
win_url URL Optional URL to redirect players on game win. No
home_url URL Optional URL to redirect players on game cancel. No
end_time Date Optional game end time. Defaults to 24 hours from creation. No

Example Request (cURL)

curl -X POST http://ludo.tzsmm.com/api/snake-create-game \
-H "Content-Type: application/json" \
-d '{
    "api_key": "your_api_key",
    "callback_url": "https://yourapp.com/callback",
    "lose_url": "https://yourapp.com/lose",
    "win_url": "https://yourapp.com/win",
    "end_time": "2025-04-14T12:00:00Z"
}'

Example Request (Python)

import requests

url = "http://ludo.tzsmm.com/api/snake-create-game"
data = {
    "api_key": "your_api_key",
    "callback_url": "https://yourapp.com/callback",
    "lose_url": "https://yourapp.com/lose",
    "win_url": "https://yourapp.com/win",
    "end_time": "2025-04-14T12:00:00Z"
}
response = requests.post(url, json=data)
print(response.json())

Example Response (Success)

{
    "status": true,
    "message": "Match Created Successfully",
    "game_id": 33,
    "player_1_id": 65,
    "player_2_id": 66,
    "player_1_url": "https://ludo.tzsmm.com/snake-game/join/RgYVQ2vyDo/7NxUaf0h",
    "player_2_url": "https://ludo.tzsmm.com/snake-game/join/RgYVQ2vyDo/zcjwlQa9"
}

Error Responses

Status Message Description
false Must Provide API key Missing or invalid API key.
false Invalid API key API key does not match any user.
false Insufficient Balance to Create The Game User’s balance is less than the match price (default: 10).
GET/POST http://ludo.tzsmm.com/api/snake-games/status

Check Snake & Ladders Game Status

Retrieves the status and details of a specific Snake & Ladders game created by the authenticated user.

Request Parameters

Parameter Type Description Required
api_key String Your unique API key for authentication. Yes
game_id Integer The ID of the game to check. Yes

Example Request (cURL)

curl -X GET "http://ludo.tzsmm.com/api/snake-games/status?api_key=your_api_key&game_id=33"

Example Request (JavaScript)

fetch('http://ludo.tzsmm.com/api/snake-games/status?api_key=your_api_key&game_id=33')
    .then(response => response.json())
    .then(data => console.log(data))
    .catch(error => console.error('Error:', error));

Example Response (Success)

{
    "status": true,
    "game_id": 33,
    "winner": null,
    "game_status": "waiting",
    "message": "Game Detailed fetched"
}

Error Responses

Status Message Description
false Must Provide API key and Game ID Missing or invalid parameters.
false Invalid API key API key does not match any user.
false Game Not Found Game ID does not exist or does not belong to the user.

Roll the Dice on Your Next Big Game!

Join a vibrant community of developers building epic Ludo and Snake & Ladders experiences with TZ LUDO API.

Get Your API Key