Matchmaking

⭐ Matchmaker

Read more about 📗 API, Authentication and Authorization (S2S).

Each matchmaker manages their own private API, separate from your organization's Edgegap API.

💺 Session Seats

If you prefer to Do It Yourself, your Game Backend may integrate Sessions for custom matchmaking.

Create a Session

post

Create a session with users. Sessions are linked to a deployment.

Authorizations
Body
app_namestringRequired

The Name of the App you want to deploy, example:

supermario
Example: demo
version_namestringOptional

The Name of the App Version you want to deploy, example:

v1.0
Example: v1.0
ip_liststring[]Optional

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"]
Example: ["1.1.1.1"]
deployment_request_idstringOptional

The request id of your deployment. If specified, the session will link to the deployment

Example: c0653765de3b
citystringOptional

If you want your session in a specific city

Example: Montreal
countrystringOptional

If you want your session in a specific country

Example: Canada
continentstringOptional

If you want your session in a specific continent

Example: North America
administrative_divisionstringOptional

If you want your session in a specific administrative division

Example: Quebec
regionstringOptional

If you want your session in a specific region

Example: North America
webhook_urlstringOptional

When your Session is Linked, Unprocessable or in Error, we will POST the session's details on the webhook_url

Example: https://webhook.com
skip_telemetrybooleanOptional

If system should skip the telemetry and use GeoBase decision only

Responses
200
Success
application/json
post
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"
}

Get a Session

get

Retrieve the information for a session.

Authorizations
Path parameters
session_idanyRequired
Responses
200
Success
application/json
get
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-07-01 12:00:28.857725",
  "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

delete

Delete a session. Once deleted, a session is no more accessible and does not have a history. The deployment associated will not be deleted.

Authorizations
Path parameters
session_idanyRequired
Responses
200
Success
application/json
delete
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"
}

Put Users in a Session

put

Add specified users to a session.

Authorizations
Path parameters
session_idanyRequired
Body
ip_liststring[]Required

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"]
Responses
200
Success
application/json
put
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
    }
  ]
}

List Users of a Session

get

List all the users of session.

Authorizations
Path parameters
session_idanyRequired
Responses
200
Success
application/json
get
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
    }
  ]
}

Delete Users From a Session

delete

Remove specified users from a session.

Authorizations
Path parameters
session_idanyRequired
Body
ip_liststring[]Required

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"]
Responses
200
Success
application/json
delete
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
    }
  ]
}

List All Sessions

get

List all the active sessions.

Authorizations
Responses
200
Success
application/json
get
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
  }
}

Delete Sessions in Bulk

post

Make a bulk delete of sessions using filters. All the sessions matching the given filters will be permanently deleted.

Authorizations
Body
Responses
200
Success
application/json
post
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"
    }
  ]
}

📍 IP Lookup

Get Your Public IP

get

Retrieve your public IP address.

Authorizations
Responses
200
Success
application/json
get
GET /v1/ip HTTP/1.1
Host: api.edgegap.com
authorization: YOUR_API_KEY
Accept: */*
{
  "public_ip": "174.91.204.75"
}

Get an IP's information

get

Lookup an IP address and return the associated information.

Authorizations
Path parameters
ipanyRequired
Responses
200
Success
application/json
get
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"
  }
}

Get IPs Information in Bulk

post

Lookup IP addresses and return the associated information. Maximum of 20 IPs.

Authorizations
Body
addressesstring[]Required

IP Addresses

Example: ["1.1.1.1"]
Responses
200
Success
application/json
post
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"
      }
    }
  ]
}

🗼 Beacons

List All Location Beacons

get

List all the active location beacons. They can be used to ping them for your matchmaking system. You cannot deploy on beacons.

Authorizations
Responses
200
Success
application/json
get
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
}

Last updated

Was this helpful?