Multiplayer API Logo Multiplayer API API Docs

Matchmaking API

Matchmaking

POST
/api/matchmaking.php/list
List all available matchmaking lobbies (requires API TOKEN)
POST
/api/matchmaking.php/create
Create matchmaking with optional password — response includes a join_token for invite links (requires API TOKEN, PLAYER TOKEN)
POST
/api/matchmaking.php/{ID}/request
Request to join matchmaking (requires API TOKEN, PLAYER TOKEN)
POST
/api/matchmaking.php/{ID}/response
Respond to join request (requires API TOKEN, PLAYER TOKEN)
GET
/api/matchmaking.php/{ID}/status
Check join request status (requires API TOKEN, PLAYER TOKEN)
GET
/api/matchmaking.php/current
Get current matchmaking status (requires API TOKEN, PLAYER TOKEN)
POST
/api/matchmaking.php/{ID}/join
Join matchmaking directly — password, or join_token to bypass it (requires API TOKEN, PLAYER TOKEN)
POST
/api/matchmaking.php/leave
Leave current matchmaking (requires API TOKEN, PLAYER TOKEN)
GET
/api/matchmaking.php/players
List all players in current matchmaking (requires API TOKEN, PLAYER TOKEN)
POST
/api/matchmaking.php/heartbeat
Send matchmaking heartbeat (requires API TOKEN, PLAYER TOKEN)
POST
/api/matchmaking.php/remove
Remove matchmaking lobby (requires API TOKEN, PLAYER TOKEN)
POST
/api/matchmaking.php/start
Start game from matchmaking (requires API TOKEN, PLAYER TOKEN)
POST
/api/matchmaking.php/stop
Stop matchmaking lobby (Host Only) (requires API TOKEN, PLAYER TOKEN)
POST
/api/matchmaking.php/kick
Kick player from matchmaking lobby (Host Only) (requires API TOKEN, PLAYER TOKEN)
POST
/api/matchmaking.php/password
Update matchmaking password (Host Only) (requires API TOKEN, PLAYER TOKEN)
POST /api/matchmaking.php/list
Request:
$ curl -X POST "/api/matchmaking.php/list" \
  -H "X-Api-Token: API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "search": "",
    "limit": 20
  }'
Response:
{
  "success": true,
  "lobbies": [
    {
      "matchmaking_id": "15b2b6e5f0ba44b5eef77705d120861f",
      "host_player_id": 62,
      "max_players": 4,
      "strict_full": 1,
      "rules": {
        "min_level": 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"
    }
  ]
}
Note: max_players in response can be between 2 and 16
POST /api/matchmaking.php/create
Request:
$ curl -X POST "/api/matchmaking.php/create" \
  -H "X-Api-Token: API_TOKEN" \
  -H "X-Game-Player-Token: PLAYER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "matchmaking_name": "My Matchmaking",
    "maxPlayers": 4,
    "strictFull": true,
    "join_by_requests": true,
    "host_switch": false,
    "can_leave_room": true,
    "rules": {
      "min_level": 10,
      "rank": "gold"
    },
    "player_data": {
      "level": 20,
      "class": "paladin",
      "inventory": ["sword", "shield", "armor"]
    }
  }'
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
Request:
$ curl -X POST "/api/matchmaking.php/15b2b6e5f0ba44b5eef77705d120861f/request" \
  -H "X-Api-Token: API_TOKEN" \
  -H "X-Game-Player-Token: PLAYER_TOKEN"
Response:
{
  "success": true,
  "request_id": "82334acd88f0af6a1f4747bbe755263a",
  "message": "Join request sent to host"
}
POST /api/matchmaking.php/REQUEST_ID/response
Request:
$ curl -X POST "/api/matchmaking.php/f4d90025b5de54e6b1a83940cffb4490/response" \
  -H "X-Api-Token: API_TOKEN" \
  -H "X-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
Request:
$ curl -X POST "/api/matchmaking.php/f4d90025b5de54e6b1a83940cffb4490/response" \
  -H "X-Api-Token: API_TOKEN" \
  -H "X-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
Request:
$ curl "/api/matchmaking.php/f4d90025b5de54e6b1a83940cffb4490/status"
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
Request:
$ curl "/api/matchmaking.php/current"
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,
    "rules": {
      "min_level": 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
Request:
$ curl -X POST "/api/matchmaking.php/15b2b6e5f0ba44b5eef77705d120861f/join" \
  -H "X-Api-Token: API_TOKEN" \
  -H "X-Game-Player-Token: PLAYER_TOKEN"
Response:
{
  "success": true,
  "matchmaking_id": "15b2b6e5f0ba44b5eef77705d120861f",
  "message": "Successfully joined matchmaking lobby"
}
POST /api/matchmaking.php/leave
Request:
$ curl -X POST "/api/matchmaking.php/leave" \
  -H "X-Api-Token: API_TOKEN" \
  -H "X-Game-Player-Token: PLAYER_TOKEN"
Response:
{
  "success": true,
  "message": "Successfully left matchmaking lobby"
}
GET /api/matchmaking.php/players
Request:
$ curl "/api/matchmaking.php/players"
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,
      "is_local": true
    },
    {
      "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,
      "is_local": false
    }
  ],
  "last_updated": "2026-03-06T17:35:59+00:00"
}
POST /api/matchmaking.php/remove
Request:
$ curl -X POST "/api/matchmaking.php/remove" \
  -H "X-Api-Token: API_TOKEN" \
  -H "X-Game-Player-Token: PLAYER_TOKEN"
Response:
{
  "success": true,
  "message": "Matchmaking lobby removed successfully"
}
POST /api/matchmaking.php/start
Request:
$ curl -X POST "/api/matchmaking.php/start" \
  -H "X-Api-Token: API_TOKEN" \
  -H "X-Game-Player-Token: PLAYER_TOKEN"
Response:
{
  "success": true,
  "room_id": "c899e32506d44823d486585b247eafe5",
  "room_name": "Game from Matchmaking 15b2b6",
  "players_transferred": 2,
  "message": "Game started successfully"
}