Multiplayer API Logo

Multiplayer API

Back to Main GitHub

REST API for
Multiplayer Games

Complete REST API with JSON responses. Real-time multiplayer, matchmaking, and game rooms.

Complete REST API documentation with examples for Unity and other platforms.

View Endpoints Authentication REST API

API Features

Built for modern multiplayer development

RESTful Design

Standard HTTP methods with predictable endpoints and consistent JSON responses.

Secure Auth

API token authentication with player-specific private keys for secure access.

Real-time Multiplayer

Matchmaking, game rooms, real-time updates, and player management systems.

API Endpoints

Complete Unity-compatible API Endpoints

Method
Endpoint
Description

Game Players

POST
/api/game_players.php/register
Register player (JSON responses)
PUT
/api/game_players.php/login
Authenticate player (JSON)
POST
/api/game_players.php/heartbeat
Update player heartbeat (JSON)
POST
/api/game_players.php/logout
Logout player (JSON)
GET
/api/game_players.php/list
List all players (JSON)

Game Data

GET
/api/game_data.php/game/get
Get game data (JSON)
PUT
/api/game_data.php/game/update
Update game data (JSON)
GET
/api/game_data.php/player/get
Get player data (returns dynamic player_data object)
PUT
/api/game_data.php/player/update
Update player data (JSON)

Leaderboard

POST
/api/leaderboard.php
Get ranked leaderboard (JSON responses)

Server Data

GET
/api/time.php
Get server time (JSON)
GET
/api/time.php?utc=+1
Get server time +1 hour offset (JSON)
GET
/api/time.php?utc=-2
Get server time -2 hours offset (JSON)

Matchmaking

GET
/api/matchmaking.php/list
List all available matchmaking lobbies (JSON)
POST
/api/matchmaking.php/create
Create matchmaking (extra_json_string for dynamic data)
POST
/api/matchmaking.php/{ID}/request
Request to join matchmaking (JSON)
POST
/api/matchmaking.php/{ID}/response
Respond to join request (JSON)
GET
/api/matchmaking.php/{ID}/status
Check join request status (JSON)
GET
/api/matchmaking.php/current
Get current matchmaking status (JSON)
POST
/api/matchmaking.php/{ID}/join
Join matchmaking directly (JSON)
POST
/api/matchmaking.php/leave
Leave current matchmaking (JSON)
GET
/api/matchmaking.php/players
List all players in current matchmaking (JSON)
POST
/api/matchmaking.php/heartbeat
Send matchmaking heartbeat (JSON)
POST
/api/matchmaking.php/remove
Remove matchmaking lobby (JSON)
POST
/api/matchmaking.php/start
Start game from matchmaking (JSON)

Game Rooms

POST
/api/game_room.php/rooms
Create game room (JSON)
GET
/api/game_room.php/rooms
List all game rooms (JSON)
POST
/api/game_room.php/rooms/{ID}/join
Join existing room (JSON)
GET
/api/game_room.php/rooms/players
List all players in current room (JSON)
POST
/api/game_room.php/rooms/leave
Leave current game room (JSON)
POST
/api/game_room.php/heartbeat
Send room heartbeat (JSON)
POST
/api/game_room.php/actions
Submit game action (JSON)
GET
/api/game_room.php/actions/poll
Get actions result (JSON)
GET
/api/game_room.php/actions/pending
View all pending actions (JSON)
POST
/api/game_room.php/actions/{ID}/complete
Complete or reject action (JSON)
POST
/api/game_room.php/updates
Send updates to players (JSON)
GET
/api/game_room.php/updates/poll
Poll for updates (JSON)
GET
/api/game_room.php/current
Get current room status (JSON)

Authentication

Secure your API requests

API Authentication

All API requests require authentication using API tokens and player private keys. This ensures secure access to game data and player information.

API Token Authentication

Include your API token in query parameters:

?api_token=YOUR_API_TOKEN
Player Authentication

Include player token for player-specific operations:

?game_player_token=PLAYER_PRIVATE_KEY
Admin Operations

Some operations require your private API token:

?api_private_token=YOUR_API_PRIVATE_TOKEN

REST API – Complete Documentation

Use our REST API directly from any platform or language. All endpoints return JSON responses with consistent error handling.

POST /api/game_players.php/register?api_token=YOUR_API_TOKEN
Request:
$ curl -X POST "/api/game_players.php/register?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "player_name": "TestPlayer",
    "player_data": {
      "level": 1,
      "score": 0,
      "inventory": ["sword", "shield"]
    }
  }'
Response:
{
  "success": true,
  "player_id": "3",
  "private_key": "cf24626c48177c7459b7bbcaa86538a93913",
  "player_name": "TestPlayer",
  "game_id": 2
}
PUT /api/game_players.php/login?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl -X PUT "/api/game_players.php/login?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN" \
  -H "Content-Type: application/json"
Response:
{
  "success": true,
  "player": {
    "id": 3,
    "game_id": 2,
    "player_name": "TestPlayer",
    "player_data": {
      "level": 1,
      "score": 0,
      "inventory": ["sword", "shield"]
    },
    "is_active": 1,
    "last_login": null,
    "last_heartbeat": null,
    "last_logout": null,
    "created_at": "2026-03-13 09:39:06",
    "updated_at": "2026-03-13 09:39:06"
  }
}
POST /api/game_players.php/heartbeat?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl -X POST "/api/game_players.php/heartbeat?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN" \
  -H "Content-Type: application/json"
Response:
{
  "success": true,
  "message": "Heartbeat updated",
  "last_heartbeat": "2026-03-13 09:46:13"
}
POST /api/game_players.php/logout?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl -X POST "/api/game_players.php/logout?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN" \
  -H "Content-Type: application/json"
Response:
{
  "success": true,
  "message": "Player logged out successfully",
  "last_logout": "2026-03-13 09:46:37"
}
GET /api/game_players.php/list?api_token=YOUR_API_TOKEN&api_private_token=YOUR_API_PRIVATE_TOKEN
Request:
$ curl -X GET "/api/game_players.php/list?api_token=YOUR_API_TOKEN&api_private_token=YOUR_API_PRIVATE_TOKEN"
Response:
{
  "success": true,
  "count": 3,
  "players": [
    {
      "id": 1,
      "player_name": "TestPlayer",
      "is_active": 1,
      "last_login": null,
      "last_logout": null,
      "last_heartbeat": null,
      "created_at": "2026-03-13 09:37:47"
    },
    {
      "id": 3,
      "player_name": "TestPlayer",
      "is_active": 1,
      "last_login": "2026-03-13 09:40:35",
      "last_logout": null,
      "last_heartbeat": null,
      "created_at": "2026-03-13 09:39:06"
    },
    {
      "id": 2,
      "player_name": "TestPlayer",
      "is_active": 1,
      "last_login": null,
      "last_logout": null,
      "last_heartbeat": null,
      "created_at": "2026-03-13 09:38:01"
    }
  ]
}
GET /api/game_data.php/game/get?api_token=YOUR_API_TOKEN
Request:
$ curl -X GET "/api/game_data.php/game/get?api_token=YOUR_API_TOKEN"
Response:
{
  "success": true,
  "type": "game",
  "game_id": 4,
  "data": {
    "text": "hello world",
    "game_settings": {
      "difficulty": "hard",
      "max_players": 10
    },
    "last_updated": "2025-01-13T12:00:00Z"
  }
}
PUT /api/game_data.php/game/update?api_token=YOUR_API_TOKEN&api_private_token=YOUR_API_PRIVATE_TOKEN
Request:
$ curl -X PUT "/api/game_data.php/game/update?api_token=YOUR_API_TOKEN&api_private_token=YOUR_API_PRIVATE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "game_settings": {
      "difficulty": "hard",
      "max_players": 10
    },
    "last_updated": "2025-01-13T12:00:00Z"
  }'
Response:
{
  "success": true,
  "message": "Game data updated successfully",
  "updated_at": "2026-01-13 14:24:23"
}
GET /api/game_data.php/player/get?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl -X GET "/api/game_data.php/player/get?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN"
Response:
{
  "success": true,
  "type": "player",
  "player_id": 7,
  "player_name": "TestPlayer",
  "data": {
    "level": 1,
    "score": 0,
    "inventory": ["sword", "shield"]
  }
}
PUT /api/game_data.php/player/update?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl -X PUT "/api/game_data.php/player/update?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "level": 2,
    "score": 100,
    "inventory": ["sword", "shield", "potion"],
    "last_played": "2025-01-13T12:30:00Z"
  }'
Response:
{
  "success": true,
  "message": "Player data updated successfully",
  "updated_at": "2026-01-13 14:27:10"
}
GET /api/time.php?api_token=YOUR_API_KEY
Request:
$ curl -X GET "/api/time.php?api_token=YOUR_API_KEY"
Response:
{
  "success": true,
  "utc": "2026-03-13T14:01:49+00:00",
  "timestamp": 1773410509,
  "readable": "2026-03-13 14:01:49 UTC"
}
GET /api/time.php?api_token=YOUR_API_KEY&utc=+1
Request:
$ curl -X GET "/api/time.php?api_token=YOUR_API_KEY&utc=+1"
Response:
{
  "success": true,
  "utc": "2026-03-13T15:04:17+00:00",
  "timestamp": 1773414257,
  "readable": "2026-03-13 15:04:17 UTC",
  "offset": {
    "offset_hours": 1,
    "offset_string": "+1",
    "original_utc": "2026-03-13T14:04:17+00:00",
    "original_timestamp": 1773410657
  }
}
GET /api/time.php?api_token=YOUR_API_KEY&utc=-2
Request:
$ curl -X GET "/api/time.php?api_token=YOUR_API_KEY&utc=-2"
Response:
{
  "success": true,
  "utc": "2026-03-13T12:05:13+00:00",
  "timestamp": 1773403513,
  "readable": "2026-03-13 12:05:13 UTC",
  "offset": {
    "offset_hours": -2,
    "offset_string": "-2",
    "original_utc": "2026-03-13T14:05:13+00:00",
    "original_timestamp": 1773410713
  }
}
POST /api/game_room.php/rooms?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl -X POST "/api/game_room.php/rooms?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "room_name": "My Game Room",
    "password": "secret123",
    "max_players": 4
  }'
Response:
{
  "success": true,
  "room_id": "dc3723848639139113ca240958ba0bf8",
  "room_name": "My Game Room",
  "is_host": true
}
GET /api/game_room.php/rooms?api_token=YOUR_API_TOKEN
Request:
$ curl -X GET "/api/game_room.php/rooms?api_token=YOUR_API_TOKEN"
Response:
{
  "success": true,
  "rooms": [
    {
      "room_id": "dc3723848639139113ca240958ba0bf8",
      "room_name": "My Game Room",
      "max_players": 4,
      "current_players": 1,
      "has_password": 1
    }
  ]
}
POST /api/game_room.php/rooms/ROOM_ID/join?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl -X POST "/api/game_room.php/rooms/dc3723848639139113ca240958ba0bf8/join?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "secret123"
  }'
Response:
{
  "success": true,
  "room_id": "dc3723848639139113ca240958ba0bf8",
  "message": "Successfully joined the room"
}
GET /api/game_room.php/players?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl -X GET "/api/game_room.php/players?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN"
Response:
{
  "success": true,
  "players": [
    {
      "player_id": "48",
      "player_name": "TestPlayer",
      "is_host": 1,
      "is_online": 1,
      "last_heartbeat": "2026-03-09 09:39:34"
    },
    {
      "player_id": "49",
      "player_name": "TestPlayer",
      "is_host": 0,
      "is_online": 1,
      "last_heartbeat": "2026-03-09 09:44:39"
    }
  ],
  "last_updated": "2026-03-09T09:56:21+00:00"
}
POST /api/game_room.php/rooms/leave?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl -X POST "/api/game_room.php/rooms/leave?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN"
Response:
{
  "success": true,
  "message": "Successfully left the room"
}
POST /api/game_room.php/heartbeat?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl -X POST "/api/game_room.php/heartbeat?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN"
Response:
{
  "success": true,
  "status": "ok"
}
POST /api/game_room.php/actions?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl -X POST "/api/game_room.php/actions?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action_type": "move",
    "request_data": {
      "x": 10,
      "y": 20
    }
  }'
Response:
{
  "success": true,
  "action_id": "1c2bbd859e36dc7d7e5e9b4f263c88ce",
  "status": "pending"
}
GET /api/game_room.php/actions/poll?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl "/api/game_room.php/actions/poll?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN"
Response:
{
  "success": true,
  "actions": [
    {
      "action_id": "efc5ea74e3a37e41a4f57d948cfb2538",
      "action_type": "move",
      "response_data": {
        "success": true,
        "message": "Moved successfully"
      },
      "status": "completed"
    }
  ]
}
GET /api/game_room.php/actions/pending?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl "/api/game_room.php/actions/pending?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN"
Response:
{
  "success": true,
  "actions": [
    {
      "action_id": "efc5ea74e3a37e41a4f57d948cfb2538",
      "player_id": "49",
      "action_type": "move",
      "request_data": {
        "x": 10,
        "y": 20
      },
      "created_at": "2026-03-09 10:10:10",
      "player_name": "TestPlayer"
    }
  ]
}
POST /api/game_room.php/actions/ACTION_ID/complete?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl -X POST "/api/game_room.php/actions/1c2bbd859e36dc7d7e5e9b4f263c88ce/complete?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed",
    "response_data": {
      "success": true,
      "message": "Moved successfully"
    }
  }'
Response:
{
  "success": true,
  "message": "Action completed"
}
POST /api/game_room.php/updates?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl -X POST "/api/game_room.php/updates?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "targetPlayerIds": "all",
    "type": "play_animation",
    "dataJson": {
      "animation": "victory",
      "duration": 2.0
    }
  }'
Response:
{
  "success": true,
  "updates_sent": 1,
  "update_ids": ["ddb19c9d8722073762f5db33ff13712a"],
  "target_players": ["47"]
}
POST /api/game_room.php/updates?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl -X POST "/api/game_room.php/updates?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "targetPlayerIds": ["47"],
    "type": "spawn_effect",
    "dataJson": {
      "effect": "explosion",
      "position": {
        "x": 10,
        "y": 20
      }
    }
  }'
Response:
{
  "success": true,
  "updates_sent": 1,
  "update_ids": ["377bfa1d4c56c3f72d9c87b0c081e6e8"],
  "target_players": ["47"]
}
GET /api/game_room.php/updates/poll?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl "/api/game_room.php/updates/poll?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN"
Response:
{
  "success": true,
  "updates": [
    {
      "update_id": "a28388775fcf9478c6926cbe44f9d3ed",
      "from_player_id": "48",
      "type": "play_animation",
      "data_json": {
        "animation": "victory",
        "duration": 2
      },
      "created_at": "2026-03-09 10:51:40"
    },
    {
      "update_id": "f26cbcdab3939b968f148edf68a9fe54",
      "from_player_id": "48",
      "type": "play_animation",
      "data_json": {
        "animation": "victory",
        "duration": 2
      },
      "created_at": "2026-03-09 10:53:58"
    },
    {
      "update_id": "374ad8d18f1a1fddf09a856d61787c5c",
      "from_player_id": "48",
      "type": "play_animation",
      "data_json": {
        "animation": "victory",
        "duration": 2
      },
      "created_at": "2026-03-09 10:54:16"
    }
  ],
  "last_update_id": "374ad8d18f1a1fddf09a856d61787c5c"
}
GET /api/game_room.php/updates/poll?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN&lastUpdateId=UPDATE_ID
Request:
$ curl "/api/game_room.php/updates/poll?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN&lastUpdateId=a28388775fcf9478c6926cbe44f9d3ed"
Response:
{
  "success": true,
  "updates": [
    {
      "update_id": "f26cbcdab3939b968f148edf68a9fe54",
      "from_player_id": "48",
      "type": "play_animation",
      "data_json": {
        "animation": "victory",
        "duration": 2
      },
      "created_at": "2026-03-09 10:53:58"
    }
  ],
  "last_update_id": "f26cbcdab3939b968f148edf68a9fe54"
}
GET /api/game_room.php/current?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl "/api/game_room.php/current?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN"
Response:
{
  "success": true,
  "in_room": true,
  "room": {
    "room_id": "05f157893b1237f7699e548d045904ab",
    "room_name": "Game from Matchmaking 636b3f",
    "is_host": false,
    "is_online": true,
    "max_players": 4,
    "current_players": 2,
    "has_password": false,
    "is_active": true,
    "player_name": "TestPlayer",
    "joined_at": "2026-03-06 17:50:35",
    "last_heartbeat": "2026-03-06 18:02:35",
    "room_created_at": "2026-03-06 17:50:35",
    "room_last_activity": "2026-03-06 18:04:58"
  },
  "pending_actions": [],
  "pending_updates": []
}
GET /api/matchmaking.php/list?api_token=YOUR_API_TOKEN
Request:
$ curl "/api/matchmaking.php/list?api_token=YOUR_API_TOKEN"
Response:
{
  "success": true,
  "lobbies": [
    {
      "matchmaking_id": "15b2b6e5f0ba44b5eef77705d120861f",
      "host_player_id": 62,
      "max_players": 4,
      "strict_full": 1,
      "extra_json_string": {
        "minLevel": 10,
        "rank": "gold"
      },
      "created_at": "2026-03-10 15:16:58",
      "last_heartbeat": "2026-03-10 15:16:58",
      "current_players": 1,
      "host_name": "TestPlayer"
    }
  ]
}
POST /api/matchmaking.php/create?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl -X POST "/api/matchmaking.php/create?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "maxPlayers": 4,
    "strictFull": true,
    "joinByRequests": true,
    "extraJsonString": {
      "minLevel": 10,
      "rank": "gold"
    }
  }'
Response:
{
  "success": true,
  "matchmaking_id": "636b3ffc9b30dc9c918d8a49661df078",
  "max_players": 4,
  "strict_full": true,
  "join_by_requests": true,
  "is_host": true
}
POST /api/matchmaking.php/MATCHMAKING_ID/request?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl -X POST "/api/matchmaking.php/15b2b6e5f0ba44b5eef77705d120861f/request?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN"
Response:
{
  "success": true,
  "request_id": "82334acd88f0af6a1f4747bbe755263a",
  "message": "Join request sent to host"
}
POST /api/matchmaking.php/REQUEST_ID/response?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl -X POST "/api/matchmaking.php/f4d90025b5de54e6b1a83940cffb4490/response?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "approve"
  }'
Response:
{
  "success": true,
  "message": "Join request approved successfully",
  "request_id": "f4d90025b5de54e6b1a83940cffb4490",
  "action": "approve"
}
POST /api/matchmaking.php/REQUEST_ID/response?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl -X POST "/api/matchmaking.php/f4d90025b5de54e6b1a83940cffb4490/response?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "reject"
  }'
Response:
{
  "success": true,
  "message": "Join request rejected successfully",
  "request_id": "f4d90025b5de54e6b1a83940cffb4490",
  "action": "reject"
}
GET /api/matchmaking.php/REQUEST_ID/status?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl "/api/matchmaking.php/f4d90025b5de54e6b1a83940cffb4490/status?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN"
Response:
{
  "success": true,
  "request": {
    "request_id": "f4d90025b5de54e6b1a83940cffb4490",
    "matchmaking_id": "15b2b6e5f0ba44b5eef77705d120861f",
    "status": "approved",
    "requested_at": "2026-03-10 16:10:23",
    "responded_at": "2026-03-10 16:18:43",
    "responded_by": 62,
    "responder_name": "TestPlayer",
    "join_by_requests": true
  }
}
GET /api/matchmaking.php/current?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl "/api/matchmaking.php/current?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN"
Response:
{
  "success": true,
  "in_matchmaking": true,
  "matchmaking": {
    "matchmaking_id": "636b3ffc9b30dc9c918d8a49661df078",
    "is_host": true,
    "max_players": 4,
    "current_players": 1,
    "strict_full": true,
    "join_by_requests": false,
    "extra_json_string": {
      "minLevel": 10,
      "rank": "gold"
    },
    "joined_at": "2026-03-06 17:23:53",
    "player_status": "active",
    "last_heartbeat": "2026-03-06 17:23:53",
    "lobby_heartbeat": "2026-03-06 17:24:37",
    "is_started": false,
    "started_at": null
  },
  "pending_requests": []
}
POST /api/matchmaking.php/MATCHMAKING_ID/join?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl -X POST "/api/matchmaking.php/15b2b6e5f0ba44b5eef77705d120861f/join?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN"
Response:
{
  "success": true,
  "matchmaking_id": "15b2b6e5f0ba44b5eef77705d120861f",
  "message": "Successfully joined matchmaking lobby"
}
POST /api/matchmaking.php/leave?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl -X POST "/api/matchmaking.php/leave?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN"
Response:
{
  "success": true,
  "message": "Successfully left matchmaking lobby"
}
GET /api/matchmaking.php/players?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl "/api/matchmaking.php/players?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN"
Response:
{
  "success": true,
  "players": [
    {
      "player_id": 47,
      "joined_at": "2026-03-06 17:23:53",
      "last_heartbeat": "2026-03-06 17:23:53",
      "status": "active",
      "player_name": "TestPlayer",
      "seconds_since_heartbeat": 726,
      "is_host": 1
    },
    {
      "player_id": 46,
      "joined_at": "2026-03-06 17:35:01",
      "last_heartbeat": "2026-03-06 17:35:01",
      "status": "active",
      "player_name": "TestPlayer",
      "seconds_since_heartbeat": 58,
      "is_host": 0
    }
  ],
  "last_updated": "2026-03-06T17:35:59+00:00"
}
POST /api/matchmaking.php/heartbeat?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl -X POST "/api/matchmaking.php/heartbeat?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN"
Response:
{
  "success": true,
  "status": "ok"
}
POST /api/matchmaking.php/remove?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl -X POST "/api/matchmaking.php/remove?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN"
Response:
{
  "success": true,
  "message": "Matchmaking lobby removed successfully"
}
POST /api/matchmaking.php/start?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN
Request:
$ curl -X POST "/api/matchmaking.php/start?api_token=YOUR_API_TOKEN&game_player_token=PLAYER_TOKEN"
Response:
{
  "success": true,
  "room_id": "c899e32506d44823d486585b247eafe5",
  "room_name": "Game from Matchmaking 15b2b6",
  "players_transferred": 2,
  "message": "Game started successfully"
}
POST /api/leaderboard.php?api_token=YOUR_API_TOKEN
Request:
$ curl -X POST "/api/leaderboard.php?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sortBy": ["level"],
    "limit": 10
  }'
Response:
{
  "success": true,
  "leaderboard": [
    {
      "rank": 1,
      "player_id": 33,
      "player_name": "GameHost",
      "player_data": {
        "level": 15,
        "rank": "platinum",
        "role": "host",
        "last_played": "2026-03-13T14:28:06.9900113Z",
        "matchmaking_status": "ready"
      }
    },
    {
      "rank": 2,
      "player_id": 35,
      "player_name": "Player2",
      "player_data": {
        "level": 12,
        "rank": "gold",
        "role": "player"
      }
    },
    {
      "rank": 3,
      "player_id": 34,
      "player_name": "Player1",
      "player_data": {
        "level": 8,
        "rank": "silver",
        "role": "player"
      }
    },
    {
      "rank": 4,
      "player_id": 36,
      "player_name": "Player3",
      "player_data": {
        "level": 6,
        "rank": "bronze",
        "role": "player"
      }
    }
  ],
  "total": 4,
  "sort_by": ["level"],
  "limit": 10
}
POST /api/leaderboard.php?api_token=YOUR_API_TOKEN
Request:
$ curl -X POST "/api/leaderboard.php?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sortBy": ["level", "score"],
    "limit": 10
  }'
Response:
{
  "success": true,
  "leaderboard": [
    {
      "rank": 1,
      "player_id": 40,
      "player_name": "TestPlayer4",
      "player_data": {
        "level": 20,
        "score": 1000,
        "inventory": []
      }
    },
    {
      "rank": 2,
      "player_id": 37,
      "player_name": "TestPlayer1",
      "player_data": {
        "level": 15,
        "score": 4500,
        "inventory": ["sword"]
      }
    },
    {
      "rank": 3,
      "player_id": 38,
      "player_name": "TestPlayer2",
      "player_data": {
        "level": 15,
        "score": 2000,
        "inventory": ["sword", "shield"]
      }
    },
    {
      "rank": 4,
      "player_id": 41,
      "player_name": "TestPlayer5",
      "player_data": {
        "level": 12,
        "inventory": ["staff"]
      }
    },
    {
      "rank": 5,
      "player_id": 39,
      "player_name": "TestPlayer3",
      "player_data": {
        "level": 8,
        "score": 3000,
        "inventory": ["bow"]
      }
    }
  ],
  "total": 5,
  "sort_by": ["level", "score"],
  "limit": 10
}
POST /api/leaderboard.php?api_token=YOUR_API_TOKEN
Request:
$ curl -X POST "/api/leaderboard.php?api_token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sortBy": ["score", "level"],
    "limit": 10
  }'
Response:
{
  "success": true,
  "leaderboard": [
    {
      "rank": 1,
      "player_id": 37,
      "player_name": "TestPlayer1",
      "player_data": {
        "level": 15,
        "score": 4500,
        "inventory": ["sword"]
      }
    },
    {
      "rank": 2,
      "player_id": 39,
      "player_name": "TestPlayer3",
      "player_data": {
        "level": 8,
        "score": 3000,
        "inventory": ["bow"]
      }
    },
    {
      "rank": 3,
      "player_id": 38,
      "player_name": "TestPlayer2",
      "player_data": {
        "level": 15,
        "score": 2000,
        "inventory": ["sword", "shield"]
      }
    },
    {
      "rank": 4,
      "player_id": 40,
      "player_name": "TestPlayer4",
      "player_data": {
        "level": 20,
        "score": 1000,
        "inventory": []
      }
    },
    {
      "rank": 5,
      "player_id": 41,
      "player_name": "TestPlayer5",
      "player_data": {
        "level": 12,
        "inventory": ["staff"]
      }
    }
  ],
  "total": 5,
  "sort_by": ["score", "level"],
  "limit": 10
}
ERROR Invalid API Token
Request:
$ curl -X POST "/api/game_players.php/register?api_token=INVALID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "player_name": "TestPlayer"
  }'
Response:
{
  "success": false,
  "error": "Invalid API token",
  "message": "Authentication failed"
}