Matchmaking
Last updated
Was this helpful?
Last updated
Was this helpful?
Read more about , and .
Each matchmaker manages their own private API, separate from your organization's Edgegap API.
If you prefer to Do It Yourself, your Game Backend may integrate Sessions for custom matchmaking.
See ⭐ Matchmaker for managed and secure client-side matchmaking alternative.
Retrieve the information for a session.
GET /v1/session/{session_id} HTTP/1.1
Host: api.edgegap.com
authorization: YOUR_API_KEY
Accept: */*
{
"session_id": "abc123-s",
"custom_id": "custom-abc123",
"status": "Ready",
"ready": true,
"linked": true,
"kind": "Seat",
"user_count": "10",
"app_version": 1,
"create_time": "2025-06-20 12:00:43.066217",
"elapsed": 1,
"error": "text",
"session_users": [
{
"ip": "1.2.3.4",
"latitude": 1,
"longitude": 1
}
],
"session_ips": [
{
"ip": "1.2.3.4",
"latitude": 1,
"longitude": 1
}
],
"deployment": {
"request_id": "abc123",
"public_ip": "100.10.0.85",
"status": "Status.READY",
"ready": true,
"whitelisting_active": true,
"fqdn": "abc123.test.edgegap.com",
"ports": {
"7777": {
"external": 31669,
"internal": 7777,
"protocol": "UDP",
"name": "7777",
"tls_upgrade": false,
"link": "example.com:31669",
"proxy": 65002
},
"web": {
"external": 31587,
"internal": 8080,
"protocol": "http",
"name": "web",
"tls_upgrade": true,
"link": "https://example.com:31587",
"proxy": 65001
}
},
"location": {
"city": "Montreal",
"country": "Canada",
"continent": "North America",
"administrative_division": "Quebec",
"timezone": "Eastern Time",
"latitude": 45.508888,
"longitude": -73.561668
},
"tags": [
"production"
],
"sockets": "5",
"sockets_usage": "2",
"is_joinable_by_session": true
},
"webhook_url": "https://webhook.com"
}Delete a session. Once deleted, a session is no more accessible and does not have a history. The deployment associated will not be deleted.
DELETE /v1/session/{session_id} HTTP/1.1
Host: api.edgegap.com
authorization: YOUR_API_KEY
Accept: */*
{
"message": "Instance 93924761ccde will be deleted",
"session_id": "abc123-s",
"custom_id": "custom-abc123"
}List all the users of session.
GET /v1/session/{session_id}/users HTTP/1.1
Host: api.edgegap.com
authorization: YOUR_API_KEY
Accept: */*
{
"session_users": [
{
"ip": "1.2.3.4",
"latitude": 1,
"longitude": 1
}
]
}List all the active sessions.
GET /v1/sessions HTTP/1.1
Host: api.edgegap.com
authorization: YOUR_API_KEY
Accept: */*
{
"data": [
{
"session_id": "abc123-s",
"custom_id": "custom-abc123",
"status": "Status.READY",
"ready": true,
"linked": true,
"kind": "DEFAULT | SEATS | MATCH",
"user_count": "10",
"deployment_request_id": "abc123",
"webhook_url": "https://webhook.com"
}
],
"total_count": 1,
"pagination": {
"number": 1,
"next_page_number": 1,
"previous_page_number": 1,
"paginator": {
"num_pages": 1
},
"has_next": true,
"has_previous": true
}
}Lookup an IP address and return the associated information.
GET /v1/ip/{ip}/lookup HTTP/1.1
Host: api.edgegap.com
authorization: YOUR_API_KEY
Accept: */*
{
"type": "IPv4",
"ip_address": "1.1.1.1",
"location": {
"continent": {
"code": "AF",
"name": "Africa"
},
"country": {
"code": "CA",
"name": "Canada"
},
"latitude": "45.4215",
"longitude": "-75.6972"
}
}List all the active location beacons. They can be used to ping them for your matchmaking system. You cannot deploy on beacons.
GET /v1/locations/beacons HTTP/1.1
Host: api.edgegap.com
authorization: YOUR_API_KEY
Accept: */*
{
"locations": [
{
"host": "text",
"fqdn": "text",
"udp_port": 1,
"tcp_port": 1,
"location": {
"city": "text",
"country": "text",
"continent": "text",
"administrative_division": "text",
"timezone": "text",
"latitude": 1,
"longitude": 1
}
}
],
"count": 1
}Add specified users to a session.
The List of IP of your user, Array of String, example:
["162.254.103.13","198.12.116.39", "162.254.135.39", "162.254.129.34"]
PUT /v1/session/{session_id}/users HTTP/1.1
Host: api.edgegap.com
authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 23
{
"ip_list": [
"1.2.3.4"
]
}{
"session_users": [
{
"ip": "1.2.3.4",
"latitude": 1,
"longitude": 1
}
]
}Remove specified users from a session.
The List of IP of your user, Array of String, example:
["162.254.103.13","198.12.116.39", "162.254.135.39", "162.254.129.34"]
DELETE /v1/session/{session_id}/users HTTP/1.1
Host: api.edgegap.com
authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 23
{
"ip_list": [
"1.2.3.4"
]
}{
"session_users": [
{
"ip": "1.2.3.4",
"latitude": 1,
"longitude": 1
}
]
}Make a bulk delete of sessions using filters. All the sessions matching the given filters will be permanently deleted.
POST /v1/sessions/bulk-stop HTTP/1.1
Host: api.edgegap.com
authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 91
{
"filters": [
{
"field": "session_id",
"values": [
"session-1",
"session-2"
],
"filter_type": "any"
}
]
}{
"processable": [
{
"session_id": "session-1"
}
]
}Lookup IP addresses and return the associated information. Maximum of 20 IPs.
IP Addresses
["1.1.1.1"]POST /v1/ips/lookup HTTP/1.1
Host: api.edgegap.com
authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 25
{
"addresses": [
"1.1.1.1"
]
}{
"addresses": [
{
"type": "IPv4",
"ip_address": "1.1.1.1",
"location": {
"continent": {
"code": "AF",
"name": "Africa"
},
"country": {
"code": "CA",
"name": "Canada"
},
"latitude": "45.4215",
"longitude": "-75.6972"
}
}
]
}Create a session with users. Sessions are linked to a deployment.
The Name of the App you want to deploy, example:
supermario
demoThe Name of the App Version you want to deploy, example:
v1.0
v1.0The List of IP of your user, Array of String, example:
["162.254.103.13","198.12.116.39", "162.254.135.39", "162.254.129.34"]
["1.1.1.1"]The request id of your deployment. If specified, the session will link to the deployment
c0653765de3bIf you want your session in a specific city
MontrealIf you want your session in a specific country
CanadaIf you want your session in a specific continent
North AmericaIf you want your session in a specific administrative division
QuebecIf you want your session in a specific region
North AmericaWhen your Session is Linked, Unprocessable or in Error, we will POST the session's details on the webhook_url
https://webhook.comIf system should skip the telemetry and use GeoBase decision only
POST /v1/session HTTP/1.1
Host: api.edgegap.com
authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 545
{
"app_name": "demo",
"version_name": "v1.0",
"ip_list": [
"1.1.1.1"
],
"geo_ip_list": [
{
"ip": "1.2.3.4",
"latitude": 1,
"longitude": 1
}
],
"deployment_request_id": "c0653765de3b",
"location": {
"latitude": 45.5,
"longitude": -73.56
},
"city": "Montreal",
"country": "Canada",
"continent": "North America",
"administrative_division": "Quebec",
"region": "North America",
"selectors": [
{
"tag": "tag",
"tag_only": false,
"env": {
"key": "KEY",
"value": "VALUE"
}
}
],
"webhook_url": "https://webhook.com",
"filters": [
{
"field": "city",
"values": [
"Montreal"
],
"filter_type": "any"
}
],
"skip_telemetry": true
}{
"session_id": "abc123-s",
"custom_id": "custom-abc123",
"app": "demo",
"version": "v1.0",
"deployment_request_id": "text",
"selectors": [
{
"tag": "tag",
"tag_only": false,
"env": {
"key": "KEY",
"value": "VALUE"
}
}
],
"webhook_url": "text"
}Swagger Web UI: deploying a matchmaker will generate an openAPI specification and a convenient web UI. Open the URL in your browser to view and test all API endpoints, and to review payload examples.