edgegap.comCommunity DiscordDashboard

Matchmaking

⭐ Matchmaker

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

106KB
mm-conf-simple-example.json
Open

Import API specification to Scalar API Web Client or Swagger Editor to inspect details.

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.

💺 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.

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
/v1/session
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
/v1/session/{session_id}
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-11-02 09:41:26.335334",
  "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
/v1/session/{session_id}
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
/v1/session/{session_id}/users
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
/v1/session/{session_id}/users
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
/v1/session/{session_id}/users
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
/v1/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
  }
}

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
/v1/sessions/bulk-stop
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"
    }
  ]
}

🗼 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
/v1/locations/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
}

PreviousIntegrationNextPeer to Peer

Last updated

Was this helpful?