Secure API requests
All API requests require authentication using API tokens and player private keys. This ensures secure access to game data and player information.
Include your API token in query parameters:
?api_token=API_TOKENInclude player token for player-specific operations:
?player_token=PLAYER_TOKENSome operations require your private API token:
?private_token=PRIVATE_TOKENUse our REST API directly from any platform or language. All endpoints return JSON responses with consistent error handling.
$ curl -X POST "/api/game_players.php/register?api_token=API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"player_name": "TestPlayer",
"player_data": {
"level": 1,
"score": 0,
"inventory": ["sword", "shield"]
}
}'{
"success": true,
"player_id": "3",
"private_key": "cf24626c48177c7459b7bbcaa86538a93913",
"player_name": "TestPlayer",
"game_id": 2
}$ curl -X PUT "/api/game_players.php/login?api_token=API_TOKEN&player_token=PLAYER_TOKEN" \
-H "Content-Type: application/json"{
"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"
}
}$ curl -X POST "/api/game_players.php/heartbeat?api_token=API_TOKEN&player_token=PLAYER_TOKEN" \
-H "Content-Type: application/json"{
"success": true,
"message": "Heartbeat updated",
"last_heartbeat": "2026-03-13 09:46:13"
}$ curl -X POST "/api/game_players.php/logout?api_token=API_TOKEN&player_token=PLAYER_TOKEN" \
-H "Content-Type: application/json"{
"success": true,
"message": "Player logged out successfully",
"last_logout": "2026-03-13 09:46:37"
}$ curl -X GET "/api/game_players.php/list?api_token=API_TOKEN&private_token=PRIVATE_TOKEN"{
"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"
}
]
}$ curl -X GET "/api/game_data.php/game/get?api_token=API_TOKEN"{
"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"
}
}$ curl -X PUT "/api/game_data.php/game/update?api_token=API_TOKEN&private_token=PRIVATE_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"game_settings": {
"difficulty": "hard",
"max_players": 10
},
"last_updated": "2025-01-13T12:00:00Z"
}'{
"success": true,
"message": "Game data updated successfully",
"updated_at": "2026-01-13 14:24:23"
}$ curl -X GET "/api/game_data.php/player/get?api_token=API_TOKEN&player_token=PLAYER_TOKEN"{
"success": true,
"type": "player",
"player_id": 7,
"player_name": "TestPlayer",
"data": {
"level": 1,
"score": 0,
"inventory": ["sword", "shield"]
}
}$ curl -X PUT "/api/game_data.php/player/update?api_token=API_TOKEN&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"
}'{
"success": true,
"message": "Player data updated successfully",
"updated_at": "2026-01-13 14:27:10"
}$ curl -X POST "/api/leaderboard.php?api_token=API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"sortBy": ["level"],
"limit": 10
}'{
"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
}$ curl -X POST "/api/leaderboard.php?api_token=API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"sortBy": ["level", "score"],
"limit": 10
}'{
"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
}$ curl -X POST "/api/leaderboard.php?api_token=API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"sortBy": ["score", "level"],
"limit": 10
}'{
"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
}$ curl -X GET "/api/time.php?api_token=API_KEY"{
"success": true,
"utc": "2026-03-13T14:01:49+00:00",
"timestamp": 1773410509,
"readable": "2026-03-13 14:01:49 UTC"
}$ curl -X GET "/api/time.php?api_token=API_KEY&utc=+1"{
"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
}
}$ curl -X GET "/api/time.php?api_token=API_KEY&utc=-2"{
"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
}
}$ curl "/api/matchmaking.php/list?api_token=API_TOKEN"{
"success": true,
"lobbies": [
{
"matchmaking_id": "15b2b6e5f0ba44b5eef77705d120861f",
"host_player_id": 62,
"max_players": 4,
"strict_full": 1,
"rules": {
"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"
}
]
}$ curl -X POST "/api/matchmaking.php/create?api_token=API_TOKEN&player_token=PLAYER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"maxPlayers": 4,
"strictFull": true,
"joinByRequests": true,
"rules": {
"minLevel": 10,
"rank": "gold"
}
}'{
"success": true,
"matchmaking_id": "636b3ffc9b30dc9c918d8a49661df078",
"max_players": 4,
"strict_full": true,
"join_by_requests": true,
"is_host": true
}$ curl -X POST "/api/matchmaking.php/15b2b6e5f0ba44b5eef77705d120861f/request?api_token=API_TOKEN&player_token=PLAYER_TOKEN"{
"success": true,
"request_id": "82334acd88f0af6a1f4747bbe755263a",
"message": "Join request sent to host"
}$ curl -X POST "/api/matchmaking.php/f4d90025b5de54e6b1a83940cffb4490/response?api_token=API_TOKEN&player_token=PLAYER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"action": "approve"
}'{
"success": true,
"message": "Join request approved successfully",
"request_id": "f4d90025b5de54e6b1a83940cffb4490",
"action": "approve"
}$ curl -X POST "/api/matchmaking.php/f4d90025b5de54e6b1a83940cffb4490/response?api_token=API_TOKEN&player_token=PLAYER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"action": "reject"
}'{
"success": true,
"message": "Join request rejected successfully",
"request_id": "f4d90025b5de54e6b1a83940cffb4490",
"action": "reject"
}$ curl "/api/matchmaking.php/f4d90025b5de54e6b1a83940cffb4490/status?api_token=API_TOKEN&player_token=PLAYER_TOKEN"{
"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
}
}$ curl "/api/matchmaking.php/current?api_token=API_TOKEN&player_token=PLAYER_TOKEN"{
"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,
"rules": {
"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": []
}$ curl -X POST "/api/matchmaking.php/15b2b6e5f0ba44b5eef77705d120861f/join?api_token=API_TOKEN&player_token=PLAYER_TOKEN"{
"success": true,
"matchmaking_id": "15b2b6e5f0ba44b5eef77705d120861f",
"message": "Successfully joined matchmaking lobby"
}$ curl -X POST "/api/matchmaking.php/leave?api_token=API_TOKEN&player_token=PLAYER_TOKEN"{
"success": true,
"message": "Successfully left matchmaking lobby"
}$ curl "/api/matchmaking.php/players?api_token=API_TOKEN&player_token=PLAYER_TOKEN"{
"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"
}$ curl -X POST "/api/matchmaking.php/heartbeat?api_token=API_TOKEN&player_token=PLAYER_TOKEN"{
"success": true,
"status": "ok"
}$ curl -X POST "/api/matchmaking.php/remove?api_token=API_TOKEN&player_token=PLAYER_TOKEN"{
"success": true,
"message": "Matchmaking lobby removed successfully"
}$ curl -X POST "/api/matchmaking.php/start?api_token=API_TOKEN&player_token=PLAYER_TOKEN"{
"success": true,
"room_id": "c899e32506d44823d486585b247eafe5",
"room_name": "Game from Matchmaking 15b2b6",
"players_transferred": 2,
"message": "Game started successfully"
}$ curl -X POST "/api/game_room.php/create?api_token=API_TOKEN&player_token=PLAYER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"room_name": "My Game Room",
"password": "secret123",
"max_players": 4
}'{
"success": true,
"room_id": "dc3723848639139113ca240958ba0bf8",
"room_name": "My Game Room",
"is_host": true
}$ curl -X GET "/api/game_room.php/list?api_token=API_TOKEN"{
"success": true,
"rooms": [
{
"room_id": "dc3723848639139113ca240958ba0bf8",
"room_name": "My Game Room",
"max_players": 4,
"current_players": 1,
"has_password": 1
}
]
}$ curl -X POST "/api/game_room.php/dc3723848639139113ca240958ba0bf8/join?api_token=API_TOKEN&player_token=PLAYER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"password": "secret123"
}'{
"success": true,
"room_id": "dc3723848639139113ca240958ba0bf8",
"message": "Successfully joined the room"
}$ curl -X GET "/api/game_room.php/players?api_token=API_TOKEN&player_token=PLAYER_TOKEN"{
"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"
}$ curl -X POST "/api/game_room.php/leave?api_token=API_TOKEN&player_token=PLAYER_TOKEN"{
"success": true,
"message": "Successfully left the room"
}$ curl -X POST "/api/game_room.php/heartbeat?api_token=API_TOKEN&player_token=PLAYER_TOKEN"{
"success": true,
"status": "ok"
}$ curl -X POST "/api/game_room.php/actions?api_token=API_TOKEN&player_token=PLAYER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"action_type": "move",
"request_data": {
"x": 10,
"y": 20
}
}'{
"success": true,
"action_id": "1c2bbd859e36dc7d7e5e9b4f263c88ce",
"status": "pending"
}$ curl "/api/game_room.php/actions/poll?api_token=API_TOKEN&player_token=PLAYER_TOKEN"{
"success": true,
"actions": [
{
"action_id": "efc5ea74e3a37e41a4f57d948cfb2538",
"action_type": "move",
"response_data": {
"success": true,
"message": "Moved successfully"
},
"status": "completed"
}
]
}$ curl "/api/game_room.php/actions/pending?api_token=API_TOKEN&player_token=PLAYER_TOKEN"{
"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"
}
]
}$ curl -X POST "/api/game_room.php/actions/1c2bbd859e36dc7d7e5e9b4f263c88ce/complete?api_token=API_TOKEN&player_token=PLAYER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"status": "completed",
"response_data": {
"success": true,
"message": "Moved successfully"
}
}'{
"success": true,
"message": "Action completed"
}$ curl -X POST "/api/game_room.php/updates?api_token=API_TOKEN&player_token=PLAYER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"target_players": "all",
"type": "play_animation",
"data": {
"animation": "victory",
"duration": 2.0
}
}'{
"success": true,
"updates_sent": 1,
"update_ids": ["ddb19c9d8722073762f5db33ff13712a"],
"target_players_ids": [47]
}$ curl -X POST "/api/game_room.php/updates?api_token=API_TOKEN&player_token=PLAYER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"target_players": "specific",
"target_players_ids": [47],
"type": "spawn_effect",
"data": {
"effect": "explosion",
"position": {
"x": 10,
"y": 20
}
}
}'{
"success": true,
"updates_sent": 1,
"update_ids": ["377bfa1d4c56c3f72d9c87b0c081e6e8"],
"target_players_ids": [47]
}$ curl "/api/game_room.php/updates/poll?api_token=API_TOKEN&player_token=PLAYER_TOKEN"{
"success": true,
"updates": [
{
"update_id": "a28388775fcf9478c6926cbe44f9d3ed",
"from_player_id": "48",
"type": "play_animation",
"data": {
"animation": "victory",
"duration": 2
},
"created_at": "2026-03-09 10:51:40"
},
{
"update_id": "f26cbcdab3939b968f148edf68a9fe54",
"from_player_id": "48",
"type": "play_animation",
"data": {
"animation": "victory",
"duration": 2
},
"created_at": "2026-03-09 10:53:58"
},
{
"update_id": "374ad8d18f1a1fddf09a856d61787c5c",
"from_player_id": "48",
"type": "play_animation",
"data": {
"animation": "victory",
"duration": 2
},
"created_at": "2026-03-09 10:54:16"
}
],
"last_update_id": "374ad8d18f1a1fddf09a856d61787c5c"
}$ curl "/api/game_room.php/updates/poll?api_token=API_TOKEN&player_token=PLAYER_TOKEN&lastUpdateId=a28388775fcf9478c6926cbe44f9d3ed"{
"success": true,
"updates": [
{
"update_id": "f26cbcdab3939b968f148edf68a9fe54",
"from_player_id": "48",
"type": "play_animation",
"data": {
"animation": "victory",
"duration": 2
},
"created_at": "2026-03-09 10:53:58"
}
],
"last_update_id": "f26cbcdab3939b968f148edf68a9fe54"
}$ curl "/api/game_room.php/current?api_token=API_TOKEN&player_token=PLAYER_TOKEN"{
"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": []
}$ curl -X POST "/api/game_players.php/register?api_token=INVALID_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"player_name": "TestPlayer"
}'{
"success": false,
"error": "Invalid API token",
"message": "Authentication failed"
}