Matchmaking

⭐ Matchmaker

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.

See ⭐ Matchmaker for managed and secure client-side matchmaking alternative.

📍 IP Lookup

🗼 Beacons

PreviousIntegration NextPeer to Peer

Last updated 3 days ago

Was this helpful?

Get a Session

Retrieve the information for a session.

get

/v1/session/{session_id}

Authorizations

Path parameters

session_idanyrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.edgegap.com//v1/session/{session_id}' \
  --header 'authorization: YOUR_API_KEY'

200

400

401

404

500

{
  "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-03-09 12:02:11.891819",
  "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"
}

Success

Delete a Session

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}

Authorizations

Path parameters

session_idanyrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://api.edgegap.com//v1/session/{session_id}' \
  --header 'authorization: YOUR_API_KEY'

200

400

401

404

410

500

{
  "message": "Instance 93924761ccde will be deleted",
  "session_id": "abc123-s",
  "custom_id": "custom-abc123"
}

Success

Put Users in a Session

Add specified users to a session.

put

/v1/session/{session_id}/users

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

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PUT \
  --url 'https://api.edgegap.com//v1/session/{session_id}/users' \
  --header 'authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "ip_list": [
      "1.2.3.4"
    ]
  }'

200

400

401

404

422

500

{
  "session_users": [
    {
      "ip": "1.2.3.4",
      "latitude": 1,
      "longitude": 1
    }
  ]
}

Success

List Users of a Session

List all the users of session.

get

/v1/session/{session_id}/users

Authorizations

Path parameters

session_idanyrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.edgegap.com//v1/session/{session_id}/users' \
  --header 'authorization: YOUR_API_KEY'

200

400

401

404

500

{
  "session_users": [
    {
      "ip": "1.2.3.4",
      "latitude": 1,
      "longitude": 1
    }
  ]
}

Success

Delete Users From a Session

Remove specified users from a session.

delete

/v1/session/{session_id}/users

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

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://api.edgegap.com//v1/session/{session_id}/users' \
  --header 'authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "ip_list": [
      "1.2.3.4"
    ]
  }'

200

400

401

404

500

{
  "session_users": [
    {
      "ip": "1.2.3.4",
      "latitude": 1,
      "longitude": 1
    }
  ]
}

Success

List All Sessions

List all the active sessions.

get

/v1/sessions

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.edgegap.com//v1/sessions' \
  --header 'authorization: YOUR_API_KEY'

200

400

401

404

500

{
  "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
  }
}

Success

Delete Sessions in Bulk

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

post

/v1/sessions/bulk-stop

Authorizations

Body

filtersobject[]required

Filters used to match with sessions

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.edgegap.com//v1/sessions/bulk-stop' \
  --header 'authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "filters": [
      {
        "field": "session_id",
        "values": [
          "session-1",
          "session-2"
        ],
        "filter_type": "any"
      }
    ]
  }'

200

400

401

500

{
  "processable": [
    {
      "session_id": "session-1"
    }
  ]
}

Success

Get Your Public IP

Retrieve your public IP address.

get

/v1/ip

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.edgegap.com//v1/ip' \
  --header 'authorization: YOUR_API_KEY'

200

401

{
  "public_ip": "174.91.204.75"
}

Success

Get an IP's information

Lookup an IP address and return the associated information.

get

/v1/ip/{ip}/lookup

Authorizations

Path parameters

ipanyrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.edgegap.com//v1/ip/{ip}/lookup' \
  --header 'authorization: YOUR_API_KEY'

200

400

401

500

{
  "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"
  }
}

Success

Get IPs Information in Bulk

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

post

/v1/ips/lookup

Authorizations

Body

addressesstring[]required

IP Addresses

Example: ["1.1.1.1"]

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.edgegap.com//v1/ips/lookup' \
  --header 'authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "addresses": [
      "1.1.1.1"
    ]
  }'

200

400

401

500

{
  "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"
      }
    }
  ]
}

Success

List All Location Beacons

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

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.edgegap.com//v1/locations/beacons' \
  --header 'authorization: YOUR_API_KEY'

200

500

{
  "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
}

Success

Create a Session

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

post

/v1/session

Authorizations

Body

app_namestringrequired

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

supermario

Example: demo

version_namestring

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

v1.0

Example: v1.0

ip_liststring[]

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"]

geo_ip_listobject[]

The list of IP of your user with their location (latitude, longitude)

deployment_request_idstring

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

Example: c0653765de3b

locationobject

If you want to specify a centroid for your session.

citystring

If you want your session in a specific city

Example: Montreal

countrystring

If you want your session in a specific country

Example: Canada

continentstring

If you want your session in a specific continent

Example: North America

administrative_divisionstring

If you want your session in a specific administrative division

Example: Quebec

regionstring

If you want your session in a specific region

Example: North America

selectorsobject[]

List of Selectors to filter potential Deployment to link and tag the Session

webhook_urlstring

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

Example: https://webhook.com

filtersobject[]

List of location filters to apply to the session

skip_telemetryboolean

If system should skip the telemetry and use GeoBase decision only

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.edgegap.com//v1/session' \
  --header 'authorization: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "app_name": "demo",
    "version_name": "v1.0",
    "ip_list": [
      "1.1.1.1"
    ],
    "geo_ip_list": [
      {
        "ip": "1.1.1.1",
        "latitude": 1,
        "longitude": 1
      }
    ],
    "deployment_request_id": "c0653765de3b",
    "location": {
      "latitude": 1,
      "longitude": 1
    },
    "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
  }'

200

400

401

404

409

422

500

{
  "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"
}

Success

⭐ Matchmaker

💺 Session Seats

📍 IP Lookup

🗼 Beacons

⭐ Matchmaker

💺 Session Seats

📍 IP Lookup

🗼 Beacons

Get a Session

Delete a Session

Put Users in a Session

List Users of a Session

Delete Users From a Session

List All Sessions

Delete Sessions in Bulk

Show child attributes

Get Your Public IP

Get an IP's information

Get IPs Information in Bulk

List All Location Beacons

Create a Session

Show child attributes

Show child attributes

Show child attributes

Show child attributes