1. Developers
  2. Documentation
Powered by OVHcloud

BattleMetrics API

The BattleMetrics API is currently under development. The API is currently in an unstable state and is subject to change. Discussions related to the API should take place in our Discord in the #api channel.

Table of Contents

Authorization

OAuth 2.0 Bearer tokens are used for authorization. You may create personal access tokens from the developers area.

The Authorization header should be included in all requests.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbiI6IjM5NzE4MDE2ZjZlYjY1NmMiLCJpYXQiOjE0NzgwMzc1MjQsIm5iZiI6MTQ3ODAzNzUyNCwiaXNzIjoiaHR0cHM6Ly93d3cuYmF0dGxlbWV0cmljcy5jb20iLCJzdWIiOiJ1cm46dXNlcjoxIn0.iwwHt2lvBxlBqcEm7HrX1b1Rb9MXcMghUY5xspluWgw

Rate Limits

To prevent abuse of the API there is a global rate limit applied to all API endpoints. If you require a higher rate limit please let us know.

Rate limits have a rolling window.

Some API methods may have additional rate limits. Information about any additional rate limits will be provided in the description of the API endpoint.

Token rate limits

You are allowed 60 requests per minute and up to 15 requests per second. Higher rate limits of 45/second and 300/minute are available for authenticated requests.

Information about rate limits are provided in the HTTP headers with the exception of the burst (15 requests/second) rate limit.

The following headers are present in all responses:

X-Rate-Limit-Limit: 60
X-Rate-Limit-Remaining: 60

References

The BattleMetrics API uses several open specifications. You may find the following resources useful.

Scopes

Scopes provide limits to API tokens. Scopes do not grant permissions, they only restrict them. Less specific scopes allow for more flexibility, but could allow much more access then is necessary. You should only request the scopes you require.

Scopes take the format of <resource>:<action>(:<additional-restriction>). The more specific the scope the more limiting it is. For example, the scope ban would allow all ban actions, ban:export:server:1 would only allow exporting bans for the server with id 1.

Scopes relevant to each resource will be included in the description.

Sorting

Some API endpoints provide sorting abilities. Sort order is ascending by default by prefixing a minus (-) symbol to an attribute you may change the sort order to descending. Multiple attributes may be sorted by providing a comma (,) separated list of attributes.

Sparse fieldsets

You may request that only some attributes be returned by an endpoint. A resource's type and id will always be included, only attributes may be excluded. To request that only some attributes be returned include a comma separated list of attributes to include in the query parameters. Refer to resource documentation below for a complete list of available attributes.

Example:

GET /bans?fields[ban]=uid,reason

Would only return the uid and reason attributes for all bans returned.

API Endpoints

Ban

Stability: prototype

The BattleMetrics ban system. Apply bans to servers, or across entire organizations. These bans will not add game specific bans using the game's ban system.

The ban resource uses the following scopes:

  • ban
  • ban:create
  • ban:read
  • ban:update
  • ban:delete
  • ban:export

Create, read, update, delete, and export scopes can be further reduced to only allow access to a single server, or organization by appending :server:<id>, or :org:<id>. For example: ban:create:org:1.

Templates

The ban reason can include dynamic fields that will be automatically populated when a kick is issued.

  • {{uid}}: The ban's uid.
  • {{admin}}: The banning admin's nickname.
  • {{duration}}: Ban duration, for example Perm, 24h, or 7d.
  • {{timeLeft}}: How long until the ban expires, for example 1d, or 3.5h. This updates dynamically so a banned player can see how long until their ban expires.
  • {{banned}}: When the player was banned. The associated organization's time zone and locale will be used to format the timestamp.
  • {{expires}}: When the ban expires. Will be "Perm" for permanent bans. The associated organization's time zone and locale will be used to format the timestamp.

Attributes

Name Type Description Example
attributes:autoAddEnabled boolean True if the ban should automatically ban new identifiers after kicking a matching player. If the ban is shared it will only add identifiers from organizations that have permManage set to true. true
attributes:expires nullable date-time When the ban should expire. If null the player will be banned permanently. "2016-11-05T14:35:51.962Z"
attributes:id string Ban ID
pattern: \d+
"42"
attributes:identifiers array An array of identifiers to ban. Can link known identifiers, or manually provided ones. [1000,{"type":"steamID","identifier":"1111111111111111","manual":true}]
attributes:nativeEnabled nullable boolean True if native bans should be issued for this ban, null to use the default from the ban list, or false to prevent native bans. The default is false if there is no associated ban list. null
attributes:note nullable string A private note to associate with the ban. Used to provide more detail than the reason could allow. "Quark was reported by another player. Video showing scam: https://example.com/video"
attributes:orgWide boolean True if the ban should be applied to all servers in your organization. orgWide is only checked for servers owned by organization who issued the ban. If the ban is shared the subscription settings of the ban list will override orgWide.
default: true
true
attributes:reason string The reason for the ban. This will be used when kicking the player from the server. Do not include private information.
Length: 1..255
"41opA0OgW - Scammer (Sisko)"
attributes:timestamp date-time Timestamp of when the ban was created "2016-10-05T14:35:51.962Z"
attributes:uid string Unique ban ID. Commonly used in reason to identify ban.
Length: 5..14
"41opA0OgW"
id string Ban ID
pattern: \d+
"42"
meta:player string Player name. Will only be available when sorting by player. "example"
relationships:banList:data:id uuid Ban ID "01234567-89ab-cdef-0123-456789abcdef"
relationships:banList:data:type string Resource type. Always banList.
one of:"banList"
"banList"
relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
relationships:player:data:id string unique identifier of player
pattern: \d+
"42"
relationships:player:data:type string Resource type. Always "player"
one of:"player"
"player"
relationships:server:data:id string unique identifier of server
pattern: \d+
"42"
relationships:server:data:type string Resource type. Always "server"
one of:"server"
"server"
relationships:user:data:id string unique identifier of user
pattern: \d+
"42"
relationships:user:data:type string Resource type. Always "user"
one of:"user"
"user"
type string Resource type. Always ban.
one of:"ban"
"ban"

Ban Create

Create a new ban. After creating the ban BattleMetrics will scan all servers that the ban applies to and kick matching players.

Requires the ban:create scope. If you do not have the ban:read scope you will receive an empty response.

POST /bans

Required Parameters

Name Type Description Example
data:attributes:autoAddEnabled boolean True if the ban should automatically ban new identifiers after kicking a matching player. If the ban is shared it will only add identifiers from organizations that have permManage set to true. true
data:attributes:expires nullable date-time When the ban should expire. If null the player will be banned permanently. "2016-11-05T14:35:51.962Z"
data:attributes:identifiers array An array of identifiers to ban. Can link known identifiers, or manually provided ones. [1000,{"type":"steamID","identifier":"1111111111111111","manual":true}]
data:attributes:nativeEnabled nullable boolean True if native bans should be issued for this ban, null to use the default from the ban list, or false to prevent native bans. The default is false if there is no associated ban list. null
data:attributes:note nullable string A private note to associate with the ban. Used to provide more detail than the reason could allow. "Quark was reported by another player. Video showing scam: https://example.com/video"
data:attributes:orgWide boolean True if the ban should be applied to all servers in your organization. orgWide is only checked for servers owned by organization who issued the ban. If the ban is shared the subscription settings of the ban list will override orgWide.
default: true
true
data:attributes:reason string The reason for the ban. This will be used when kicking the player from the server. Do not include private information.
Length: 1..255
"41opA0OgW - Scammer (Sisko)"
data:attributes:timestamp date-time Timestamp of when the ban was created "2016-10-05T14:35:51.962Z"
data:attributes:uid string Unique ban ID. Commonly used in reason to identify ban.
Length: 5..14
"41opA0OgW"
data:relationships:banList:data:id uuid Ban ID "01234567-89ab-cdef-0123-456789abcdef"
data:relationships:banList:data:type string Resource type. Always banList.
one of:"banList"
"banList"
data:relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
data:relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
data:relationships:player:data:id string unique identifier of player
pattern: \d+
"42"
data:relationships:player:data:type string Resource type. Always "player"
one of:"player"
"player"
data:relationships:server:data:id string unique identifier of server
pattern: \d+
"42"
data:relationships:server:data:type string Resource type. Always "server"
one of:"server"
"server"
data:relationships:trigger:data:id uuid Trigger ID "01234567-89ab-cdef-0123-456789abcdef"
data:relationships:trigger:data:type string Resource type. Always trigger.
one of:"trigger"
"trigger"
data:relationships:user:data:id string unique identifier of user
pattern: \d+
"42"
data:relationships:user:data:type string Resource type. Always "user"
one of:"user"
"user"
data:type string
one of:"ban"
"ban"

Curl Example

$ curl -n -X POST https://api.battlemetrics.com/bans \
  -d '{
  "data": {
    "type": "ban",
    "attributes": {
      "uid": "41opA0OgW",
      "timestamp": "2016-10-05T14:35:51.962Z",
      "reason": "41opA0OgW - Scammer (Sisko)",
      "note": "Quark was reported by another player. Video showing scam: https://example.com/video",
      "expires": "2016-11-05T14:35:51.962Z",
      "identifiers": [
        1000,
        {
          "type": "steamID",
          "identifier": "1111111111111111",
          "manual": true
        }
      ],
      "orgWide": true,
      "autoAddEnabled": true,
      "nativeEnabled": null
    },
    "relationships": {
      "player": {
        "data": {
          "type": "player",
          "id": "42"
        }
      },
      "server": {
        "data": {
          "type": "server",
          "id": "42"
        }
      },
      "organization": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      },
      "user": {
        "data": {
          "type": "user",
          "id": "42"
        }
      },
      "banList": {
        "data": {
          "type": "banList",
          "id": "01234567-89ab-cdef-0123-456789abcdef"
        }
      },
      "trigger": {
        "data": {
          "type": "trigger",
          "id": "01234567-89ab-cdef-0123-456789abcdef"
        }
      }
    }
  }
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 201 Created
{
  "data": {
    "type": "ban",
    "id": "42",
    "attributes": {
      "id": "42",
      "uid": "41opA0OgW",
      "timestamp": "2016-10-05T14:35:51.962Z",
      "reason": "41opA0OgW - Scammer (Sisko)",
      "note": "Quark was reported by another player. Video showing scam: https://example.com/video",
      "expires": "2016-11-05T14:35:51.962Z",
      "identifiers": [
        1000,
        {
          "type": "steamID",
          "identifier": "1111111111111111",
          "manual": true
        }
      ],
      "orgWide": true,
      "autoAddEnabled": true,
      "nativeEnabled": null
    },
    "meta": {
      "player": "example"
    },
    "relationships": {
      "player": {
        "data": {
          "type": "player",
          "id": "42"
        }
      },
      "server": {
        "data": {
          "type": "server",
          "id": "42"
        }
      },
      "organization": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      },
      "user": {
        "data": {
          "type": "user",
          "id": "42"
        }
      },
      "banList": {
        "data": {
          "type": "banList",
          "id": "01234567-89ab-cdef-0123-456789abcdef"
        }
      },
      "trigger": {
        "data": {
          "type": "trigger",
          "id": "01234567-89ab-cdef-0123-456789abcdef"
        }
      }
    }
  }
}

Ban Import

Allows you to add multiple bans at once. This method of adding bans has a few limitations.

  • It will not kick players already online.
  • It will not log each ban to server activity.
  • The bans will not immediately be available in search.

Requires the ban:import scope. If you do not have the ban:read scope you will receive an empty or partial response.

POST /bans/import

Optional Parameters

Name Type Description Example
data/attributes:autoAddEnabled boolean True if the ban should automatically ban new identifiers after kicking a matching player. If the ban is shared it will only add identifiers from organizations that have permManage set to true. true
data/attributes:expires nullable date-time When the ban should expire. If null the player will be banned permanently. "2016-11-05T14:35:51.962Z"
data/attributes:identifiers array An array of identifiers to ban. Can link known identifiers, or manually provided ones. [1000,{"type":"steamID","identifier":"1111111111111111","manual":true}]
data/attributes:nativeEnabled nullable boolean True if native bans should be issued for this ban, null to use the default from the ban list, or false to prevent native bans. The default is false if there is no associated ban list. null
data/attributes:note nullable string A private note to associate with the ban. Used to provide more detail than the reason could allow. "Quark was reported by another player. Video showing scam: https://example.com/video"
data/attributes:orgWide boolean True if the ban should be applied to all servers in your organization. orgWide is only checked for servers owned by organization who issued the ban. If the ban is shared the subscription settings of the ban list will override orgWide.
default: true
true
data/attributes:reason string The reason for the ban. This will be used when kicking the player from the server. Do not include private information.
Length: 1..255
"41opA0OgW - Scammer (Sisko)"
data/attributes:timestamp date-time Timestamp of when the ban was created "2016-10-05T14:35:51.962Z"
data/attributes:uid string Unique ban ID. Commonly used in reason to identify ban.
Length: 5..14
"41opA0OgW"
data/relationships:banList:data:id uuid Ban ID "01234567-89ab-cdef-0123-456789abcdef"
data/relationships:banList:data:type string Resource type. Always banList.
one of:"banList"
"banList"
data/relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
data/relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
data/relationships:player:data:id string unique identifier of player
pattern: \d+
"42"
data/relationships:player:data:type string Resource type. Always "player"
one of:"player"
"player"
data/relationships:server:data:id string unique identifier of server
pattern: \d+
"42"
data/relationships:server:data:type string Resource type. Always "server"
one of:"server"
"server"
data/type string
one of:"ban"
"ban"

Curl Example

$ curl -n -X POST https://api.battlemetrics.com/bans/import \
  -d '{
  "data": [
    {
      "type": "ban",
      "attributes": {
        "uid": "41opA0OgW",
        "timestamp": "2016-10-05T14:35:51.962Z",
        "reason": "41opA0OgW - Scammer (Sisko)",
        "note": "Quark was reported by another player. Video showing scam: https://example.com/video",
        "expires": "2016-11-05T14:35:51.962Z",
        "identifiers": [
          1000,
          {
            "type": "steamID",
            "identifier": "1111111111111111",
            "manual": true
          }
        ],
        "orgWide": true,
        "autoAddEnabled": true,
        "nativeEnabled": null
      },
      "relationships": {
        "player": {
          "data": {
            "type": "player",
            "id": "42"
          }
        },
        "server": {
          "data": {
            "type": "server",
            "id": "42"
          }
        },
        "organization": {
          "data": {
            "type": "organization",
            "id": "42"
          }
        },
        "banList": {
          "data": {
            "type": "banList",
            "id": "01234567-89ab-cdef-0123-456789abcdef"
          }
        }
      }
    }
  ]
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 201
{
  "type": "ban",
  "id": "42",
  "attributes": {
    "id": "42",
    "uid": "41opA0OgW",
    "timestamp": "2016-10-05T14:35:51.962Z",
    "reason": "41opA0OgW - Scammer (Sisko)",
    "note": "Quark was reported by another player. Video showing scam: https://example.com/video",
    "expires": "2016-11-05T14:35:51.962Z",
    "identifiers": [
      1000,
      {
        "type": "steamID",
        "identifier": "1111111111111111",
        "manual": true
      }
    ],
    "orgWide": true,
    "autoAddEnabled": true,
    "nativeEnabled": null
  },
  "meta": {
    "player": "example"
  },
  "relationships": {
    "player": {
      "data": {
        "type": "player",
        "id": "42"
      }
    },
    "server": {
      "data": {
        "type": "server",
        "id": "42"
      }
    },
    "organization": {
      "data": {
        "type": "organization",
        "id": "42"
      }
    },
    "user": {
      "data": {
        "type": "user",
        "id": "42"
      }
    },
    "banList": {
      "data": {
        "type": "banList",
        "id": "01234567-89ab-cdef-0123-456789abcdef"
      }
    },
    "trigger": {
      "data": {
        "type": "trigger",
        "id": "01234567-89ab-cdef-0123-456789abcdef"
      }
    }
  }
}

Allows you to export your bans to multiple game formats. Some formats do not support as much information as the BattleMetrics ban system. Exports will contain as much information as possible.

  • arma2/bans.txt: Only supports ip and BE GUID bans.
  • arma3/bans.txt: Only supports ip and BE GUID bans.
  • squad/Bans.cfg: Only supports Steam ID bans.
  • ark/banlist.txt: Only supports Steam ID bans.
  • rust/bans.cfg: Only supports Steam ID bans.
  • rust/bansip_SERVER.ini: Only supports IP bans.

Requires the ban:export scope.

GET /bans/export

Required Parameters

Name Type Description Example
format string
one of:"arma2/bans.txt" or "arma3/bans.txt" or "squad/Bans.cfg" or "ark/banlist.txt" or "rust/bans.cfg" or "rust/bansip_SERVER.ini"
"arma2/bans.txt"

Optional Parameters

Name Type Description Example
filter:organization string unique identifier of organization
pattern: \d+
"42"
filter:server string unique identifier of server
pattern: \d+
"42"

Curl Example

$ curl -n https://api.battlemetrics.com/bans/export
 -G \
  -d filter[server]=42 \
  -d filter[organization]=42 \
  -d format=arma2%2Fbans.txt

Response Example

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa -1 gWopA0OgW
127.0.0.1 -1 gWopA0OgW

Delete an existing ban. Requires the ban:delete scope.

DELETE /bans/{ban_id}

Curl Example

$ curl -n -X DELETE https://api.battlemetrics.com/bans/$BAN_ID \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 204 No Content

Info for existing ban. Requires the ban:read scope.

GET /bans/{ban_id}

Optional Parameters

Name Type Description Example
fields:ban string Request that only some attributes are returned "uid,reason"
fields:banExemption string Request that only some attributes are returned "reason"
fields:banList string Request that only some attributes are returned "name,action"
fields:identifier string Request that only some attributes are returned "type,identifier"
fields:organization string Request that only some attributes are returned "tz,banTemplate"
fields:player string Request that only some attributes are returned "updatedAt,name"
fields:server string Request that only some attributes are returned "name,ip,port"
fields:user string Request that only some attributes are returned "nickname"
include string Relations to include. Comma separated. Valid values: organization, player, playerIdentifiers, server, user, banList, banExemption "server,player"

Curl Example

$ curl -n https://api.battlemetrics.com/bans/$BAN_ID
 -G \
  -d include=server%2Cplayer \
  -d fields[ban]=uid%2Creason \
  -d fields[organization]=tz%2CbanTemplate \
  -d fields[player]=updatedAt%2Cname \
  -d fields[identifier]=type%2Cidentifier \
  -d fields[server]=name%2Cip%2Cport \
  -d fields[user]=nickname \
  -d fields[banList]=name%2Caction \
  -d fields[banExemption]=reason

Response Example

HTTP/2.0 200 OK
{
  "data": {
    "type": "ban",
    "id": "42",
    "attributes": {
      "id": "42",
      "uid": "41opA0OgW",
      "timestamp": "2016-10-05T14:35:51.962Z",
      "reason": "41opA0OgW - Scammer (Sisko)",
      "note": "Quark was reported by another player. Video showing scam: https://example.com/video",
      "expires": "2016-11-05T14:35:51.962Z",
      "identifiers": [
        1000,
        {
          "type": "steamID",
          "identifier": "1111111111111111",
          "manual": true
        }
      ],
      "orgWide": true,
      "autoAddEnabled": true,
      "nativeEnabled": null
    },
    "meta": {
      "player": "example"
    },
    "relationships": {
      "player": {
        "data": {
          "type": "player",
          "id": "42"
        }
      },
      "server": {
        "data": {
          "type": "server",
          "id": "42"
        }
      },
      "organization": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      },
      "user": {
        "data": {
          "type": "user",
          "id": "42"
        }
      },
      "banList": {
        "data": {
          "type": "banList",
          "id": "01234567-89ab-cdef-0123-456789abcdef"
        }
      },
      "trigger": {
        "data": {
          "type": "trigger",
          "id": "01234567-89ab-cdef-0123-456789abcdef"
        }
      }
    }
  },
  "included": [
    null
  ]
}

List, search and filter existing bans. By default only ban information is included. If you wish to included server and player information be sure to request the needed information.

Requires the ban:read scope.

GET /bans

Optional Parameters

Name Type Description Example
fields:ban string Request that only some attributes are returned "uid,reason"
fields:banExemption string Request that only some attributes are returned "reason"
fields:banList string Request that only some attributes are returned "name,action"
fields:organization string Request that only some attributes are returned "tz,banTemplate"
fields:player string Request that only some attributes are returned "updatedAt,name"
fields:server string Request that only some attributes are returned "name,ip,port"
fields:user string Request that only some attributes are returned "nickname"
filter:banList uuid Ban ID "01234567-89ab-cdef-0123-456789abcdef"
filter:exempt string If true show bans with exemptions. If false hide bans with exemptions.
one of:"true" or "false"
"true"
filter:expired string If true, show expired, otherwise hide expired bans.
one of:"true" or "false"
"true"
filter:organization string unique identifier of organization
pattern: \d+
"42"
filter:player string unique identifier of player
pattern: \d+
"42"
filter:search string Search term(s) "41opA0OgW"
filter:server string unique identifier of server
pattern: \d+
"42"
filter:users string Comma separated list of user ids "example"
include string Relations to include. Comma separated. "server,player"
page:key string Page key. The value to start from. The prev and next links provide this value automatically. It's recommended that you don't manually provide this value. "100"
page:rel string Direction. Next/prev records based on key.
one of:"next" or "prev"
"next"
page:size integer Number of bans to return per page
default: 10
Range: 1 <= value <= 100
42
sort string Sorting options. timestamp, expires, player, reason
default: "-timestamp"
"-timestamp,player"

Curl Example

$ curl -n https://api.battlemetrics.com/bans
 -G \
  -d filter[expired]=true \
  -d filter[exempt]=true \
  -d filter[server]=42 \
  -d filter[organization]=42 \
  -d filter[player]=42 \
  -d filter[banList]=01234567-89ab-cdef-0123-456789abcdef \
  -d filter[users]=example \
  -d filter[search]=41opA0OgW \
  -d page[size]=42 \
  -d page[key]=100 \
  -d page[rel]=next \
  -d include=server%2Cplayer \
  -d sort=-timestamp%2Cplayer \
  -d fields[ban]=uid%2Creason \
  -d fields[organization]=tz%2CbanTemplate \
  -d fields[player]=updatedAt%2Cname \
  -d fields[server]=name%2Cip%2Cport \
  -d fields[user]=nickname \
  -d fields[banList]=name%2Caction \
  -d fields[banExemption]=reason

Response Example

HTTP/2.0 200 OK
{
  "meta": {
    "active": 50,
    "expired": 50,
    "total": 100
  },
  "data": [
    {
      "type": "ban",
      "id": "42",
      "attributes": {
        "id": "42",
        "uid": "41opA0OgW",
        "timestamp": "2016-10-05T14:35:51.962Z",
        "reason": "41opA0OgW - Scammer (Sisko)",
        "note": "Quark was reported by another player. Video showing scam: https://example.com/video",
        "expires": "2016-11-05T14:35:51.962Z",
        "identifiers": [
          1000,
          {
            "type": "steamID",
            "identifier": "1111111111111111",
            "manual": true
          }
        ],
        "orgWide": true,
        "autoAddEnabled": true,
        "nativeEnabled": null
      },
      "meta": {
        "player": "example"
      },
      "relationships": {
        "player": {
          "data": {
            "type": "player",
            "id": "42"
          }
        },
        "server": {
          "data": {
            "type": "server",
            "id": "42"
          }
        },
        "organization": {
          "data": {
            "type": "organization",
            "id": "42"
          }
        },
        "user": {
          "data": {
            "type": "user",
            "id": "42"
          }
        },
        "banList": {
          "data": {
            "type": "banList",
            "id": "01234567-89ab-cdef-0123-456789abcdef"
          }
        },
        "trigger": {
          "data": {
            "type": "trigger",
            "id": "01234567-89ab-cdef-0123-456789abcdef"
          }
        }
      }
    }
  ],
  "included": [

  ],
  "links": {
    "next": "https://api.battlemetrics.com/bans?page[size]=10&key=2016-10-05T14:35:51.962Z",
    "prev": "https://api.battlemetrics.com/bans?page[size]=10&key=2015-10-05T14:35:51.962Z"
  }
}

Update an existing ban. Requires the ban:update scope. If you do not have the ban:read scope you will receive an empty response.

In addition to ban:update requests to associate the ban with a new server or organization will require ban:create.

PATCH /bans/{ban_id}

Required Parameters

Name Type Description Example
data:type string Resource type. Always ban.
one of:"ban"
"ban"

Optional Parameters

Name Type Description Example
data:attributes:autoAddEnabled boolean True if the ban should automatically ban new identifiers after kicking a matching player. If the ban is shared it will only add identifiers from organizations that have permManage set to true. true
data:attributes:expires nullable date-time When the ban should expire. If null the player will be banned permanently. "2016-11-05T14:35:51.962Z"
data:attributes:identifiers array An array of identifiers to ban. Can link known identifiers, or manually provided ones. [1000,{"type":"steamID","identifier":"1111111111111111","manual":true}]
data:attributes:nativeEnabled nullable boolean True if native bans should be issued for this ban, null to use the default from the ban list, or false to prevent native bans. The default is false if there is no associated ban list. null
data:attributes:note nullable string A private note to associate with the ban. Used to provide more detail than the reason could allow. "Quark was reported by another player. Video showing scam: https://example.com/video"
data:attributes:orgWide boolean True if the ban should be applied to all servers in your organization. orgWide is only checked for servers owned by organization who issued the ban. If the ban is shared the subscription settings of the ban list will override orgWide.
default: true
true
data:attributes:reason string The reason for the ban. This will be used when kicking the player from the server. Do not include private information.
Length: 1..255
"41opA0OgW - Scammer (Sisko)"
data:id string Ban ID
pattern: \d+
"42"
data:relationships:banList:data:id uuid Ban ID "01234567-89ab-cdef-0123-456789abcdef"
data:relationships:banList:data:type string Resource type. Always banList.
one of:"banList"
"banList"
data:relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
data:relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
data:relationships:player:data:id string unique identifier of player
pattern: \d+
"42"
data:relationships:player:data:type string Resource type. Always "player"
one of:"player"
"player"
data:relationships:server:data:id string unique identifier of server
pattern: \d+
"42"
data:relationships:server:data:type string Resource type. Always "server"
one of:"server"
"server"
data:relationships:trigger:data:id uuid Trigger ID "01234567-89ab-cdef-0123-456789abcdef"
data:relationships:trigger:data:type string Resource type. Always trigger.
one of:"trigger"
"trigger"
data:relationships:user:data:id string unique identifier of user
pattern: \d+
"42"
data:relationships:user:data:type string Resource type. Always "user"
one of:"user"
"user"

Curl Example

$ curl -n -X PATCH https://api.battlemetrics.com/bans/$BAN_ID \
  -d '{
  "data": {
    "type": "ban",
    "id": "42",
    "attributes": {
      "reason": "41opA0OgW - Scammer (Sisko)",
      "note": "Quark was reported by another player. Video showing scam: https://example.com/video",
      "expires": "2016-11-05T14:35:51.962Z",
      "identifiers": [
        1000,
        {
          "type": "steamID",
          "identifier": "1111111111111111",
          "manual": true
        }
      ],
      "orgWide": true,
      "autoAddEnabled": true,
      "nativeEnabled": null
    },
    "relationships": {
      "player": {
        "data": {
          "type": "player",
          "id": "42"
        }
      },
      "server": {
        "data": {
          "type": "server",
          "id": "42"
        }
      },
      "organization": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      },
      "user": {
        "data": {
          "type": "user",
          "id": "42"
        }
      },
      "banList": {
        "data": {
          "type": "banList",
          "id": "01234567-89ab-cdef-0123-456789abcdef"
        }
      },
      "trigger": {
        "data": {
          "type": "trigger",
          "id": "01234567-89ab-cdef-0123-456789abcdef"
        }
      }
    }
  }
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 200 OK
{
  "type": "ban",
  "id": "42",
  "attributes": {
    "id": "42",
    "uid": "41opA0OgW",
    "timestamp": "2016-10-05T14:35:51.962Z",
    "reason": "41opA0OgW - Scammer (Sisko)",
    "note": "Quark was reported by another player. Video showing scam: https://example.com/video",
    "expires": "2016-11-05T14:35:51.962Z",
    "identifiers": [
      1000,
      {
        "type": "steamID",
        "identifier": "1111111111111111",
        "manual": true
      }
    ],
    "orgWide": true,
    "autoAddEnabled": true,
    "nativeEnabled": null
  },
  "meta": {
    "player": "example"
  },
  "relationships": {
    "player": {
      "data": {
        "type": "player",
        "id": "42"
      }
    },
    "server": {
      "data": {
        "type": "server",
        "id": "42"
      }
    },
    "organization": {
      "data": {
        "type": "organization",
        "id": "42"
      }
    },
    "user": {
      "data": {
        "type": "user",
        "id": "42"
      }
    },
    "banList": {
      "data": {
        "type": "banList",
        "id": "01234567-89ab-cdef-0123-456789abcdef"
      }
    },
    "trigger": {
      "data": {
        "type": "trigger",
        "id": "01234567-89ab-cdef-0123-456789abcdef"
      }
    }
  }
}

Ban List Exemption

Stability: prototype

BattleMetrics ban list exemption.

Attributes

Name Type Description Example
attributes:reason nullable string Reason for exemption null
id uuid Ban Exemption ID "01234567-89ab-cdef-0123-456789abcdef"
relationships:ban:data:id string Ban ID
pattern: \d+
"42"
relationships:ban:data:type string Resource type. Always ban.
one of:"ban"
"ban"
relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
type string Resource type. Always banExemption.
one of:"banExemption"
"banExemption"

Ban List Exemption Create

Create a new ban exemption.

POST /bans/{ban_id}/relationships/exemptions

Required Parameters

Name Type Description Example
data:relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
data:relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
data:type string Resource type. Always banExemption.
one of:"banExemption"
"banExemption"

Optional Parameters

Name Type Description Example
data:attributes:reason nullable string Reason for exemption null

Curl Example

$ curl -n -X POST https://api.battlemetrics.com/bans/$BAN_ID/relationships/exemptions \
  -d '{
  "data": {
    "type": "banExemption",
    "attributes": {
      "reason": null
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      }
    }
  }
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 201 Created
{
  "data": {
    "type": "banExemption",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "attributes": {
      "reason": null
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organization",
          "id": "1"
        }
      },
      "ban": {
        "data": {
          "type": "ban",
          "id": "1"
        }
      }
    }
  }
}

Get info on a ban exemption.

GET /bans/{ban_id}/relationships/exemptions/{banExemption_id}

Curl Example

$ curl -n https://api.battlemetrics.com/bans/$BAN_ID/relationships/exemptions/$BANEXEMPTION_ID

Response Example

HTTP/2.0 200 OK
{
  "data": {
    "type": "banExemption",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "attributes": {
      "reason": null
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organization",
          "id": "1"
        }
      },
      "ban": {
        "data": {
          "type": "ban",
          "id": "1"
        }
      }
    }
  }
}

Get exemptions.

GET /bans/{ban_id}/relationships/exemptions

Optional Parameters

Name Type Description Example
fields:banExemption string Request that only some attributes are returned "reason"

Curl Example

$ curl -n https://api.battlemetrics.com/bans/$BAN_ID/relationships/exemptions
 -G \
  -d fields[banExemption]=reason

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "type": "banExemption",
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "attributes": {
        "reason": null
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organization",
            "id": "1"
          }
        },
        "ban": {
          "data": {
            "type": "ban",
            "id": "1"
          }
        }
      }
    }
  ]
}

Update a ban exemption.

PATCH /bans/{ban_id}/relationships/exemptions

Optional Parameters

Name Type Description Example
data:attributes:reason nullable string Reason for exemption null
data:id uuid Ban Exemption ID "01234567-89ab-cdef-0123-456789abcdef"
data:relationships:ban:data:id string Ban ID
pattern: \d+
"42"
data:relationships:ban:data:type string Resource type. Always ban.
one of:"ban"
"ban"
data:relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
data:relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
data:type string Resource type. Always banExemption.
one of:"banExemption"
"banExemption"

Curl Example

$ curl -n -X PATCH https://api.battlemetrics.com/bans/$BAN_ID/relationships/exemptions \
  -d '{
  "data": {
    "type": "banExemption",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "attributes": {
      "reason": null
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organization",
          "id": "1"
        }
      },
      "ban": {
        "data": {
          "type": "ban",
          "id": "1"
        }
      }
    }
  }
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 204 No Content

Delete a ban exemption.

DELETE /bans/{ban_id}/relationships/exemptions

Curl Example

$ curl -n -X DELETE https://api.battlemetrics.com/bans/$BAN_ID/relationships/exemptions \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 204 No Content

Ban List

Stability: prototype

BattleMetrics ban list management.

Attributes

Name Type Description Example
attributes:action string Action to take when a player who is on this list joins. Action may be null when set on individual servers. If it is null then the default value of the ban list will be used.
one of:"none" or "log" or "kick"
"none"
attributes:defaultAutoAddEnabled boolean Determines if auto add should be enabled by default in the BattleMetrics interface. true
attributes:defaultIdentifiers array A list of identifiers that should be banned by default. These types will be selected automatically when banning players. It does not impact bans issued through the API.
default: []
["steamID","ip"]
attributes:defaultNativeEnabled nullable boolean If bans should have native bans enabled by default. null
attributes:defaultReasons array A list of default reasons that should be presented to the user in the BattleMetrics interface.
default: []
["{{uid}} - Reason - ({{admin}})"]
attributes:name string Ban List name "example"
attributes:nativeBanPermMaxExpires nullable integer Minutes. If the game supports bans that expire we will not issue bans that last longer than this value for permanent bans. Null for no maximum. null
attributes:nativeBanTTL nullable integer Minutes. How long a ban should stay in a game's native ban system before it's removed. Default is 7 days. Many games have issues with ban lists that are too large. It is recommended you don't leave bans in too long. null
attributes:nativeBanTempMaxExpires nullable integer Minutes. If the game supports bans that expire we will not issue bans that last longer than this value for temporary bans. Null for no maximum. null
attributes:permCreate boolean True if this organization has permission to create bans for this list. true
attributes:permDelete boolean True if this organization has permission to delete bans on this list. true
attributes:permManage boolean True if this organization has permission to manage other organization's subscriptions to this ban list. true
attributes:permUpdate boolean True if this organization has permission to update bans on this list. true
id uuid Ban ID "01234567-89ab-cdef-0123-456789abcdef"
relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
relationships:owner:data:id string unique identifier of organization
pattern: \d+
"42"
relationships:owner:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
relationships:servers:data nullable array null
relationships:servers:data/id string unique identifier of server
pattern: \d+
"42"
relationships:servers:data/meta nullable object null
relationships:servers:data/meta:action string Action to take when a player who is on this list joins. Action may be null when set on individual servers. If it is null then the default value of the ban list will be used.
relationships:servers:data/meta:defaultNativeEnabled nullable boolean If bans should have native bans enabled by default. null
relationships:servers:data/meta:nativeBanPermMaxExpires nullable integer Minutes. If the game supports bans that expire we will not issue bans that last longer than this value for permanent bans. Null for no maximum. null
relationships:servers:data/meta:nativeBanTTL nullable integer Minutes. How long a ban should stay in a game's native ban system before it's removed. Default is 7 days. Many games have issues with ban lists that are too large. It is recommended you don't leave bans in too long. null
relationships:servers:data/meta:nativeBanTempMaxExpires nullable integer Minutes. If the game supports bans that expire we will not issue bans that last longer than this value for temporary bans. Null for no maximum. null
relationships:servers:data/type string Resource type. Always "server"
one of:"server"
"server"
type string Resource type. Always banList.
one of:"banList"
"banList"

Ban List Create

Create a new ban list.

POST /ban-lists

Required Parameters

Name Type Description Example
data:attributes:action string Action to take when a player who is on this list joins. Action may be null when set on individual servers. If it is null then the default value of the ban list will be used.
one of:"none" or "log" or "kick"
"none"
data:attributes:defaultAutoAddEnabled boolean Determines if auto add should be enabled by default in the BattleMetrics interface. true
data:attributes:defaultIdentifiers array A list of identifiers that should be banned by default. These types will be selected automatically when banning players. It does not impact bans issued through the API.
default: []
["steamID","ip"]
data:attributes:defaultNativeEnabled nullable boolean If bans should have native bans enabled by default. null
data:attributes:defaultReasons array A list of default reasons that should be presented to the user in the BattleMetrics interface.
default: []
["{{uid}} - Reason - ({{admin}})"]
data:attributes:name string Ban List name "example"
data:attributes:nativeBanPermMaxExpires nullable integer Minutes. If the game supports bans that expire we will not issue bans that last longer than this value for permanent bans. Null for no maximum. null
data:attributes:nativeBanTTL nullable integer Minutes. How long a ban should stay in a game's native ban system before it's removed. Default is 7 days. Many games have issues with ban lists that are too large. It is recommended you don't leave bans in too long. null
data:attributes:nativeBanTempMaxExpires nullable integer Minutes. If the game supports bans that expire we will not issue bans that last longer than this value for temporary bans. Null for no maximum. null
data:relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
data:relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
data:relationships:owner:data:id string unique identifier of organization
pattern: \d+
"42"
data:relationships:owner:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
data:relationships:servers:data nullable array null
data:relationships:servers:data/id string unique identifier of server
pattern: \d+
"42"
data:relationships:servers:data/meta nullable object null
data:relationships:servers:data/meta:action string Action to take when a player who is on this list joins. Action may be null when set on individual servers. If it is null then the default value of the ban list will be used.
data:relationships:servers:data/meta:defaultNativeEnabled nullable boolean If bans should have native bans enabled by default. null
data:relationships:servers:data/meta:nativeBanPermMaxExpires nullable integer Minutes. If the game supports bans that expire we will not issue bans that last longer than this value for permanent bans. Null for no maximum. null
data:relationships:servers:data/meta:nativeBanTTL nullable integer Minutes. How long a ban should stay in a game's native ban system before it's removed. Default is 7 days. Many games have issues with ban lists that are too large. It is recommended you don't leave bans in too long. null
data:relationships:servers:data/meta:nativeBanTempMaxExpires nullable integer Minutes. If the game supports bans that expire we will not issue bans that last longer than this value for temporary bans. Null for no maximum. null
data:relationships:servers:data/type string Resource type. Always "server"
one of:"server"
"server"
data:type string Resource type. Always banList.
one of:"banList"
"banList"

Curl Example

$ curl -n -X POST https://api.battlemetrics.com/ban-lists \
  -d '{
  "data": {
    "type": "banList",
    "attributes": {
      "name": "example",
      "action": "none",
      "defaultIdentifiers": [
        "steamID",
        "ip"
      ],
      "defaultReasons": [
        "{{uid}} - Reason - ({{admin}})"
      ],
      "defaultAutoAddEnabled": true,
      "defaultNativeEnabled": true,
      "nativeBanTTL": null,
      "nativeBanTempMaxExpires": null,
      "nativeBanPermMaxExpires": null
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organization",
          "id": "1"
        }
      },
      "owner": {
        "data": {
          "type": "organization",
          "id": "1"
        }
      }
    }
  }
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 201 Created
{
  "data": {
    "type": "banList",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "attributes": {
      "name": "example",
      "action": "none",
      "permManage": true,
      "permCreate": true,
      "permUpdate": true,
      "permDelete": true,
      "defaultIdentifiers": [
        "steamID",
        "ip"
      ],
      "defaultReasons": [
        "{{uid}} - Reason - ({{admin}})"
      ],
      "defaultAutoAddEnabled": true,
      "defaultNativeEnabled": true,
      "nativeBanTTL": null,
      "nativeBanTempMaxExpires": null,
      "nativeBanPermMaxExpires": null
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organization",
          "id": "1"
        }
      },
      "owner": {
        "data": {
          "type": "organization",
          "id": "1"
        }
      }
    }
  }
}

Ban List Create

Accept a ban list invite.

POST /ban-lists/accept-invite

Required Parameters

Name Type Description Example
data:attributes:action string Action to take when a player who is on this list joins. Action may be null when set on individual servers. If it is null then the default value of the ban list will be used.
one of:"none" or "log" or "kick"
"none"
data:attributes:code string Ban Invite ID
pattern: ^[A-z0-9_-]+
Length: 7..14
"rygK6AV7YW"
data:attributes:defaultAutoAddEnabled boolean Determines if auto add should be enabled by default in the BattleMetrics interface. true
data:attributes:defaultIdentifiers array A list of identifiers that should be banned by default. These types will be selected automatically when banning players. It does not impact bans issued through the API.
default: []
["steamID","ip"]
data:attributes:defaultNativeEnabled nullable boolean If bans should have native bans enabled by default. null
data:attributes:defaultReasons array A list of default reasons that should be presented to the user in the BattleMetrics interface.
default: []
["{{uid}} - Reason - ({{admin}})"]
data:attributes:nativeBanPermMaxExpires nullable integer Minutes. If the game supports bans that expire we will not issue bans that last longer than this value for permanent bans. Null for no maximum. null
data:attributes:nativeBanTTL nullable integer Minutes. How long a ban should stay in a game's native ban system before it's removed. Default is 7 days. Many games have issues with ban lists that are too large. It is recommended you don't leave bans in too long. null
data:attributes:nativeBanTempMaxExpires nullable integer Minutes. If the game supports bans that expire we will not issue bans that last longer than this value for temporary bans. Null for no maximum. null
data:relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
data:relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
data:relationships:owner:data:id string unique identifier of organization
pattern: \d+
"42"
data:relationships:owner:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
data:relationships:servers:data nullable array null
data:relationships:servers:data/id string unique identifier of server
pattern: \d+
"42"
data:relationships:servers:data/meta nullable object null
data:relationships:servers:data/meta:action string Action to take when a player who is on this list joins. Action may be null when set on individual servers. If it is null then the default value of the ban list will be used.
data:relationships:servers:data/meta:defaultNativeEnabled nullable boolean If bans should have native bans enabled by default. null
data:relationships:servers:data/meta:nativeBanPermMaxExpires nullable integer Minutes. If the game supports bans that expire we will not issue bans that last longer than this value for permanent bans. Null for no maximum. null
data:relationships:servers:data/meta:nativeBanTTL nullable integer Minutes. How long a ban should stay in a game's native ban system before it's removed. Default is 7 days. Many games have issues with ban lists that are too large. It is recommended you don't leave bans in too long. null
data:relationships:servers:data/meta:nativeBanTempMaxExpires nullable integer Minutes. If the game supports bans that expire we will not issue bans that last longer than this value for temporary bans. Null for no maximum. null
data:relationships:servers:data/type string Resource type. Always "server"
one of:"server"
"server"
data:type string Resource type. Always banList.
one of:"banList"
"banList"

Curl Example

$ curl -n -X POST https://api.battlemetrics.com/ban-lists/accept-invite \
  -d '{
  "data": {
    "type": "banList",
    "attributes": {
      "code": "rygK6AV7YW",
      "action": "none",
      "defaultIdentifiers": [
        "steamID",
        "ip"
      ],
      "defaultReasons": [
        "{{uid}} - Reason - ({{admin}})"
      ],
      "defaultAutoAddEnabled": true,
      "defaultNativeEnabled": true,
      "nativeBanTTL": null,
      "nativeBanTempMaxExpires": null,
      "nativeBanPermMaxExpires": null
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organization",
          "id": "1"
        }
      },
      "owner": {
        "data": {
          "type": "organization",
          "id": "1"
        }
      }
    }
  }
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 200 OK
{
  "data": {
    "type": "banList",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "attributes": {
      "name": "example",
      "action": "none",
      "permManage": true,
      "permCreate": true,
      "permUpdate": true,
      "permDelete": true,
      "defaultIdentifiers": [
        "steamID",
        "ip"
      ],
      "defaultReasons": [
        "{{uid}} - Reason - ({{admin}})"
      ],
      "defaultAutoAddEnabled": true,
      "defaultNativeEnabled": true,
      "nativeBanTTL": null,
      "nativeBanTempMaxExpires": null,
      "nativeBanPermMaxExpires": null
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organization",
          "id": "1"
        }
      },
      "owner": {
        "data": {
          "type": "organization",
          "id": "1"
        }
      }
    }
  }
}

List ban lists you own, or are subscribed to.

GET /ban-lists

Optional Parameters

Name Type Description Example
fields:banList string Request that only some attributes are returned "name,action"
fields:organization string Request that only some attributes are returned "tz,banTemplate"
fields:owner string Request that only some attributes are returned "tz,banTemplate"
fields:server string Request that only some attributes are returned "name,ip,port"
include string Relations to include. Comma separated. Valid values: organization,owner,server "server"
page:key string Page key. The value to start from. The prev and next links provide this value automatically. It's recommended that you don't manually provide this value. "100"
page:rel string Direction. Next/prev records based on key.
one of:"next" or "prev"
"next"
page:size integer Number of items to return per page
default: 10
Range: 1 <= value <= 100
42

Curl Example

$ curl -n https://api.battlemetrics.com/ban-lists
 -G \
  -d include=server \
  -d fields[organization]=tz%2CbanTemplate \
  -d fields[owner]=tz%2CbanTemplate \
  -d fields[server]=name%2Cip%2Cport \
  -d fields[banList]=name%2Caction \
  -d page[size]=42 \
  -d page[key]=100 \
  -d page[rel]=next

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "type": "banList",
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "attributes": {
        "name": "example",
        "action": "none",
        "permManage": true,
        "permCreate": true,
        "permUpdate": true,
        "permDelete": true,
        "defaultIdentifiers": [
          "steamID",
          "ip"
        ],
        "defaultReasons": [
          "{{uid}} - Reason - ({{admin}})"
        ],
        "defaultAutoAddEnabled": true,
        "defaultNativeEnabled": true,
        "nativeBanTTL": null,
        "nativeBanTempMaxExpires": null,
        "nativeBanPermMaxExpires": null
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organization",
            "id": "1"
          }
        },
        "owner": {
          "data": {
            "type": "organization",
            "id": "1"
          }
        }
      }
    }
  ],
  "included": [

  ],
  "links": {
    "next": "https://api.battlemetrics.com/ban-lists?page[size]=10&key=example",
    "prev": "https://api.battlemetrics.com/ban-lists?page[size]=10&key=example"
  }
}

List organizations that are subscribed to the list. You must own the list, or have permManage to use this endpoint.

GET /ban-lists/{banList_id}/relationships/organizations

Optional Parameters

Name Type Description Example
fields:banList string Request that only some attributes are returned "name,action"
fields:organization string Request that only some attributes are returned "tz,banTemplate"
fields:owner string Request that only some attributes are returned "tz,banTemplate"
fields:server string Request that only some attributes are returned "name,ip,port"
include string Relations to include. Comma separated. Valid values: organization,owner,server "server"
page:key string Page key. The value to start from. The prev and next links provide this value automatically. It's recommended that you don't manually provide this value. "100"
page:rel string Direction. Next/prev records based on key.
one of:"next" or "prev"
"next"
page:size integer Number of items to return per page
default: 10
Range: 1 <= value <= 100
42

Curl Example

$ curl -n https://api.battlemetrics.com/ban-lists/$BANLIST_ID/relationships/organizations
 -G \
  -d include=server \
  -d fields[organization]=tz%2CbanTemplate \
  -d fields[owner]=tz%2CbanTemplate \
  -d fields[server]=name%2Cip%2Cport \
  -d fields[banList]=name%2Caction \
  -d page[size]=42 \
  -d page[key]=100 \
  -d page[rel]=next

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "type": "banList",
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "attributes": {
        "name": "example",
        "action": "none",
        "permManage": true,
        "permCreate": true,
        "permUpdate": true,
        "permDelete": true,
        "defaultIdentifiers": [
          "steamID",
          "ip"
        ],
        "defaultReasons": [
          "{{uid}} - Reason - ({{admin}})"
        ],
        "defaultAutoAddEnabled": true,
        "defaultNativeEnabled": true,
        "nativeBanTTL": null,
        "nativeBanTempMaxExpires": null,
        "nativeBanPermMaxExpires": null
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organization",
            "id": "1"
          }
        },
        "owner": {
          "data": {
            "type": "organization",
            "id": "1"
          }
        }
      }
    }
  ],
  "included": [

  ],
  "links": {
    "next": "https://api.battlemetrics.com/ban-lists/c4f069ac-89c6-11e7-8ea1-4709fbe2f894/relationships/organizations?page[size]=10&key=example",
    "prev": "https://api.battlemetrics.com/ban-lists/c4f069ac-89c6-11e7-8ea1-4709fbe2f894/relationships/organizations?page[size]=10&key=example"
  }
}

Get an organization's subscription information.

GET /ban-lists/{banList_id}/relationships/organizations/{organization_id}

Optional Parameters

Name Type Description Example
fields:banList string Request that only some attributes are returned "name,action"
fields:organization string Request that only some attributes are returned "tz,banTemplate"
fields:owner string Request that only some attributes are returned "tz,banTemplate"
fields:server string Request that only some attributes are returned "name,ip,port"
include string Relations to include. Comma separated. Valid values: organization,owner,server "server"

Curl Example

$ curl -n https://api.battlemetrics.com/ban-lists/$BANLIST_ID/relationships/organizations/$ORGANIZATION_ID
 -G \
  -d include=server \
  -d fields[organization]=tz%2CbanTemplate \
  -d fields[owner]=tz%2CbanTemplate \
  -d fields[server]=name%2Cip%2Cport \
  -d fields[banList]=name%2Caction

Response Example

HTTP/2.0 200 OK
{
  "data": {
    "type": "banList",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "attributes": {
      "name": "example",
      "action": "none",
      "permManage": true,
      "permCreate": true,
      "permUpdate": true,
      "permDelete": true,
      "defaultIdentifiers": [
        "steamID",
        "ip"
      ],
      "defaultReasons": [
        "{{uid}} - Reason - ({{admin}})"
      ],
      "defaultAutoAddEnabled": true,
      "defaultNativeEnabled": true,
      "nativeBanTTL": null,
      "nativeBanTempMaxExpires": null,
      "nativeBanPermMaxExpires": null
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organization",
          "id": "1"
        }
      },
      "owner": {
        "data": {
          "type": "organization",
          "id": "1"
        }
      }
    }
  },
  "included": [

  ]
}

Get the name of a ban list by id.

GET /ban-lists/{banList_id}

Optional Parameters

Name Type Description Example
fields:owner string Request that only some attributes are returned "tz,banTemplate"
include string Relations to include. Comma separated. Valid values: owner "owner"

Curl Example

$ curl -n https://api.battlemetrics.com/ban-lists/$BANLIST_ID
 -G \
  -d include=owner \
  -d fields[owner]=tz%2CbanTemplate

Response Example

HTTP/2.0 200 OK
{
  "data": {
    "type": "banList",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "attributes": {
      "name": "example"
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organization",
          "id": "1"
        }
      },
      "owner": {
        "data": {
          "type": "organization",
          "id": "1"
        }
      }
    }
  },
  "included": [

  ]
}

Update a ban list. You must be the owner of the ban list to change the name of the ban list.

PATCH /ban-lists/{banList_id}/relationships/organizations/{organization_id}

Optional Parameters

Name Type Description Example
data:attributes:action string Action to take when a player who is on this list joins. Action may be null when set on individual servers. If it is null then the default value of the ban list will be used.
one of:"none" or "log" or "kick"
"none"
data:attributes:defaultAutoAddEnabled boolean Determines if auto add should be enabled by default in the BattleMetrics interface. true
data:attributes:defaultIdentifiers array A list of identifiers that should be banned by default. These types will be selected automatically when banning players. It does not impact bans issued through the API.
default: []
["steamID","ip"]
data:attributes:defaultNativeEnabled nullable boolean If bans should have native bans enabled by default. null
data:attributes:defaultReasons array A list of default reasons that should be presented to the user in the BattleMetrics interface.
default: []
["{{uid}} - Reason - ({{admin}})"]
data:attributes:name string Ban List name "example"
data:attributes:nativeBanPermMaxExpires nullable integer Minutes. If the game supports bans that expire we will not issue bans that last longer than this value for permanent bans. Null for no maximum. null
data:attributes:nativeBanTTL nullable integer Minutes. How long a ban should stay in a game's native ban system before it's removed. Default is 7 days. Many games have issues with ban lists that are too large. It is recommended you don't leave bans in too long. null
data:attributes:nativeBanTempMaxExpires nullable integer Minutes. If the game supports bans that expire we will not issue bans that last longer than this value for temporary bans. Null for no maximum. null
data:attributes:permCreate boolean True if this organization has permission to create bans for this list. true
data:attributes:permDelete boolean True if this organization has permission to delete bans on this list. true
data:attributes:permManage boolean True if this organization has permission to manage other organization's subscriptions to this ban list. true
data:attributes:permUpdate boolean True if this organization has permission to update bans on this list. true
data:id uuid Ban ID "01234567-89ab-cdef-0123-456789abcdef"
data:relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
data:relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
data:relationships:owner:data:id string unique identifier of organization
pattern: \d+
"42"
data:relationships:owner:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
data:relationships:servers:data nullable array null
data:relationships:servers:data/id string unique identifier of server
pattern: \d+
"42"
data:relationships:servers:data/meta nullable object null
data:relationships:servers:data/meta:action string Action to take when a player who is on this list joins. Action may be null when set on individual servers. If it is null then the default value of the ban list will be used.
data:relationships:servers:data/meta:defaultNativeEnabled nullable boolean If bans should have native bans enabled by default. null
data:relationships:servers:data/meta:nativeBanPermMaxExpires nullable integer Minutes. If the game supports bans that expire we will not issue bans that last longer than this value for permanent bans. Null for no maximum. null
data:relationships:servers:data/meta:nativeBanTTL nullable integer Minutes. How long a ban should stay in a game's native ban system before it's removed. Default is 7 days. Many games have issues with ban lists that are too large. It is recommended you don't leave bans in too long. null
data:relationships:servers:data/meta:nativeBanTempMaxExpires nullable integer Minutes. If the game supports bans that expire we will not issue bans that last longer than this value for temporary bans. Null for no maximum. null
data:relationships:servers:data/type string Resource type. Always "server"
one of:"server"
"server"
data:type string Resource type. Always banList.
one of:"banList"
"banList"

Curl Example

$ curl -n -X PATCH https://api.battlemetrics.com/ban-lists/$BANLIST_ID/relationships/organizations/$ORGANIZATION_ID \
  -d '{
  "data": {
    "type": "banList",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "attributes": {
      "name": "example",
      "action": "none",
      "permManage": true,
      "permCreate": true,
      "permUpdate": true,
      "permDelete": true,
      "defaultIdentifiers": [
        "steamID",
        "ip"
      ],
      "defaultReasons": [
        "{{uid}} - Reason - ({{admin}})"
      ],
      "defaultAutoAddEnabled": true,
      "defaultNativeEnabled": true,
      "nativeBanTTL": null,
      "nativeBanTempMaxExpires": null,
      "nativeBanPermMaxExpires": null
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organization",
          "id": "1"
        }
      },
      "owner": {
        "data": {
          "type": "organization",
          "id": "1"
        }
      }
    }
  }
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 204 No Content

Unsubscribe from a ban list.

DELETE /ban-lists/{banList_id}/relationships/organizations/{organization_id}

Curl Example

$ curl -n -X DELETE https://api.battlemetrics.com/ban-lists/$BANLIST_ID/relationships/organizations/$ORGANIZATION_ID \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 204 No Content

Ban List Invite

Stability: prototype

BattleMetrics ban list invite.

Attributes

Name Type Description Example
attributes:limit nullable integer The number of times this invite is allowed to be used. If null then the invite is good for an unlimited number of uses.
default: 1
null
attributes:permCreate boolean The value the organization who accepts this invite will be give for the associated permission. true
attributes:permDelete boolean The value the organization who accepts this invite will be give for the associated permission. true
attributes:permManage boolean The value the organization who accepts this invite will be give for the associated permission. true
attributes:permUpdate boolean The value the organization who accepts this invite will be give for the associated permission. true
attributes:uses integer The number of times this invite has been used. 42
id string Ban Invite ID
pattern: ^[A-z0-9_-]+
Length: 7..14
"rygK6AV7YW"
relationships:banList:data:id uuid Ban ID "01234567-89ab-cdef-0123-456789abcdef"
relationships:banList:data:type string Resource type. Always banList.
one of:"banList"
"banList"
relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
relationships:user:data:id string unique identifier of user
pattern: \d+
"42"
relationships:user:data:type string Resource type. Always "user"
one of:"user"
"user"
type string Resource type. Always banListInvite.
one of:"banListInvite"
"banListInvite"

Ban List Invite Create

Create a new invite.

POST /ban-lists/{banList_id}/relationships/invites

Required Parameters

Name Type Description Example
data:relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
data:relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
data:type string Resource type. Always banListInvite.
one of:"banListInvite"
"banListInvite"

Optional Parameters

Name Type Description Example
data:attributes:limit nullable integer The number of times this invite is allowed to be used. If null then the invite is good for an unlimited number of uses.
default: 1
null
data:attributes:permCreate boolean The value the organization who accepts this invite will be give for the associated permission. true
data:attributes:permDelete boolean The value the organization who accepts this invite will be give for the associated permission. true
data:attributes:permManage boolean The value the organization who accepts this invite will be give for the associated permission. true
data:attributes:permUpdate boolean The value the organization who accepts this invite will be give for the associated permission. true
data:attributes:uses integer The number of times this invite has been used. 42

Curl Example

$ curl -n -X POST https://api.battlemetrics.com/ban-lists/$BANLIST_ID/relationships/invites \
  -d '{
  "data": {
    "type": "banListInvite",
    "attributes": {
      "uses": 42,
      "limit": 42,
      "permManage": true,
      "permCreate": true,
      "permUpdate": true,
      "permDelete": true
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      }
    }
  }
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 201 Created
{
  "data": {
    "type": "banListInvite",
    "id": "rygK6AV7YW",
    "attributes": {
      "uses": 42,
      "limit": 42,
      "permManage": true,
      "permCreate": true,
      "permUpdate": true,
      "permDelete": true
    },
    "relationships": {
      "banList": {
        "data": {
          "type": "banList",
          "id": "01234567-89ab-cdef-0123-456789abcdef"
        }
      },
      "organization": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      },
      "user": {
        "data": {
          "type": "user",
          "id": "42"
        }
      }
    }
  }
}

Get info on an invite.

GET /ban-list-invites/{banListInvite_id}

Optional Parameters

Name Type Description Example
fields:banList string Request that only some attributes are returned "name,action"
fields:banListInvite string Request that only some attributes are returned "uses"
fields:organization string Request that only some attributes are returned "tz,banTemplate"
fields:user string Request that only some attributes are returned "nickname"
include string Relations to include. Comma separated. Valid values: organization,user,banList "banList"

Curl Example

$ curl -n https://api.battlemetrics.com/ban-list-invites/$BANLISTINVITE_ID
 -G \
  -d include=banList \
  -d fields[organization]=tz%2CbanTemplate \
  -d fields[user]=nickname \
  -d fields[banList]=name%2Caction \
  -d fields[banListInvite]=uses

Response Example

HTTP/2.0 200 OK
{
  "data": {
    "type": "banListInvite",
    "id": "rygK6AV7YW",
    "attributes": {
      "uses": 42,
      "limit": 42,
      "permManage": true,
      "permCreate": true,
      "permUpdate": true,
      "permDelete": true
    },
    "relationships": {
      "banList": {
        "data": {
          "type": "banList",
          "id": "01234567-89ab-cdef-0123-456789abcdef"
        }
      },
      "organization": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      },
      "user": {
        "data": {
          "type": "user",
          "id": "42"
        }
      }
    }
  },
  "included": [

  ]
}

List invites.

GET /ban-lists/{banList_id}/relationships/invites

Optional Parameters

Name Type Description Example
fields:banList string Request that only some attributes are returned "name,action"
fields:banListInvite string Request that only some attributes are returned "uses"
fields:organization string Request that only some attributes are returned "tz,banTemplate"
fields:user string Request that only some attributes are returned "nickname"
include string Relations to include. Comma separated. Valid values: organization,user,banList "banList"
page:key string Page key. The value to start from. The prev and next links provide this value automatically. It's recommended that you don't manually provide this value. "100"
page:rel string Direction. Next/prev records based on key.
one of:"next" or "prev"
"next"
page:size integer Number of items to return per page
default: 10
Range: 1 <= value <= 100
42

Curl Example

$ curl -n https://api.battlemetrics.com/ban-lists/$BANLIST_ID/relationships/invites
 -G \
  -d include=banList \
  -d fields[organization]=tz%2CbanTemplate \
  -d fields[user]=nickname \
  -d fields[banList]=name%2Caction \
  -d fields[banListInvite]=uses \
  -d page[size]=42 \
  -d page[key]=100 \
  -d page[rel]=next

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "type": "banListInvite",
      "id": "rygK6AV7YW",
      "attributes": {
        "uses": 42,
        "limit": 42,
        "permManage": true,
        "permCreate": true,
        "permUpdate": true,
        "permDelete": true
      },
      "relationships": {
        "banList": {
          "data": {
            "type": "banList",
            "id": "01234567-89ab-cdef-0123-456789abcdef"
          }
        },
        "organization": {
          "data": {
            "type": "organization",
            "id": "42"
          }
        },
        "user": {
          "data": {
            "type": "user",
            "id": "42"
          }
        }
      }
    }
  ],
  "included": [

  ],
  "links": {
    "next": "https://api.battlemetrics.com/ban-lists/eb41620e-8cec-11e7-a78d-03816ea7c7f0/relationships/invites?page[size]=10&key=example",
    "prev": "https://api.battlemetrics.com/ban-lists/eb41620e-8cec-11e7-a78d-03816ea7c7f0/relationships/invites?page[size]=10&key=example"
  }
}

Delete an invite.

DELETE /ban-lists/{banList_id}/relationships/invites/{banListInvite_id}

Curl Example

$ curl -n -X DELETE https://api.battlemetrics.com/ban-lists/$BANLIST_ID/relationships/invites/$BANLISTINVITE_ID \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 204 No Content

Native Ban

Stability: prototype

A game specific, native ban.

Attributes

Name Type Description Example
attributes:createdAt date-time Timestamp of when the native ban was issued. "2016-10-05T14:35:51.962Z"
attributes:expires nullable date-time When the native ban should expire. "2016-11-05T14:35:51.962Z"
attributes:identifier string The Identifier "76561197960265720"
attributes:reason nullable string The reason for the ban. May be null if the game does not support reasons.
Length: 1..255
"41opA0OgW - Scammer (Sisko)"
attributes:state string Ban state.
one of:"added" or "removed"
"added"
attributes:type string Identifier type
one of:"steamID" or "BEGUID" or "legacyBEGUID" or "ip" or "name" or "survivorName" or "steamFamilyShareOwner" or "conanCharName" or "egsID" or "eosID" or "funcomID" or "playFabID" or "mcUUID" or "7dtdEOS" or "battlebitHWID" or "hllWindowsID" or "palworldUID"
"steamID"
attributes:updateAt date-time The next scheduled update. "2016-10-05T14:35:51.962Z"
attributes:updatedAt date-time The last time the ban was updated. "2016-10-05T14:35:51.962Z"
id uuid Native ban ID "01234567-89ab-cdef-0123-456789abcdef"
relationships:ban:data:id string Ban ID
pattern: \d+
"42"
relationships:ban:data:type string Resource type. Always ban.
one of:"ban"
"ban"
relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
relationships:server:data:id string unique identifier of server
pattern: \d+
"42"
relationships:server:data:type string Resource type. Always "server"
one of:"server"
"server"
type string Resource type. Always banNative.
one of:"banNative"
"banNative"

List native bans. Requires the ban:read scope.

GET /bans-native

Optional Parameters

Name Type Description Example
fields:ban string Request that only some attributes are returned "uid,reason"
fields:banNative string Request that only some attributes are returned "createdAt,reason"
fields:organization string Request that only some attributes are returned "tz,banTemplate"
fields:server string Request that only some attributes are returned "name,ip,port"
filter:ban string Ban ID
pattern: \d+
"42"
filter:server string unique identifier of server
pattern: \d+
"42"
include string Relations to include. Comma separated. Valid values are ban, server, and organization "server,ban"
page:key string Page key. The value to start from. The prev and next links provide this value automatically. It's recommended that you don't manually provide this value. "100"
page:rel string Direction. Next/prev records based on key.
one of:"next" or "prev"
"next"
page:size integer Number of bans to return per page
default: 10
Range: 1 <= value <= 100
42
sort string Sorting options. createdAt, updatedAt, updateAt
default: "-createdAt"
"-createdAt,updatedAt"

Curl Example

$ curl -n https://api.battlemetrics.com/bans-native
 -G \
  -d filter[server]=42 \
  -d filter[ban]=42 \
  -d page[size]=42 \
  -d page[key]=100 \
  -d page[rel]=next \
  -d include=server%2Cban \
  -d sort=-createdAt%2CupdatedAt \
  -d fields[ban]=uid%2Creason \
  -d fields[server]=name%2Cip%2Cport \
  -d fields[organization]=tz%2CbanTemplate \
  -d fields[banNative]=createdAt%2Creason

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "type": "banNative",
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "attributes": {
        "state": "added",
        "createdAt": "2016-10-05T14:35:51.962Z",
        "updatedAt": "2016-10-05T14:35:51.962Z",
        "updateAt": "2016-10-05T14:35:51.962Z",
        "reason": "41opA0OgW - Scammer (Sisko)",
        "expires": "2016-11-05T14:35:51.962Z",
        "type": "steamID",
        "identifier": "76561197960265720"
      },
      "relationships": {
        "ban": {
          "data": {
            "type": "ban",
            "id": "42"
          }
        },
        "server": {
          "data": {
            "type": "server",
            "id": "42"
          }
        },
        "organization": {
          "data": {
            "type": "organization",
            "id": "42"
          }
        }
      }
    }
  ],
  "included": [

  ],
  "links": {
    "next": "https://api.battlemetrics.com/bans-native?page[size]=10&key=2016-10-05T14:35:51.962Z",
    "prev": "https://api.battlemetrics.com/bans-native?page[size]=10&key=2015-10-05T14:35:51.962Z"
  }
}

Native Ban Force Update

Force Update will cause us to immediately queue the ban to be updated/checked on.

POST /bans-native/{banNative_id}/force-update

Curl Example

$ curl -n -X POST https://api.battlemetrics.com/bans-native/$BANNATIVE_ID/force-update \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 202
{
  "type": "banNative",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "attributes": {
    "state": "added",
    "createdAt": "2016-10-05T14:35:51.962Z",
    "updatedAt": "2016-10-05T14:35:51.962Z",
    "updateAt": "2016-10-05T14:35:51.962Z",
    "reason": "41opA0OgW - Scammer (Sisko)",
    "expires": "2016-11-05T14:35:51.962Z",
    "type": "steamID",
    "identifier": "76561197960265720"
  },
  "relationships": {
    "ban": {
      "data": {
        "type": "ban",
        "id": "42"
      }
    },
    "server": {
      "data": {
        "type": "server",
        "id": "42"
      }
    },
    "organization": {
      "data": {
        "type": "organization",
        "id": "42"
      }
    }
  }
}

Commands Activity

Stability: prototype

Lists which commands have been used and how many times. May optionally be related to a user. The resource attributes are key value where the key is a command and the value is how many times it was executed.

Attributes

Name Type Description Example
id string commandStats id. (:).
pattern: \d+(:\d+)?
"1:1"
relationships:games:data/id string unique identifier of game
pattern: [a-z0-9]+
"ark"
relationships:games:data/type string Resource type. Always "game"
one of:"game"
"game"
relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
relationships:user:data:id string unique identifier of user
pattern: \d+
"42"
relationships:user:data:type string Resource type. Always "user"
one of:"user"
"user"
type string Resource type. Always "commandStats"
one of:"commandStats"
"commandStats"

List organization users

GET /organizations/{organization_id}/relationships/command-stats

Optional Parameters

Name Type Description Example
filter:commands string Comma separated list of commands to return "addBMBan,raw"
filter:servers string Comma separated list of server ids "example"
filter:summary boolean If true return a single result that is the merged and summed result of the resources you would normally receive. true
filter:timestamp string Filter activity by time range.
pattern: ^((\d{4})(-(\d{2}))??(-(\d{2}))??(T(\d{2}):(\d{2})(:(\d{2}))??(\.(\d+))??(([\+\-]{1}\d{2}:\d{2})&#124;Z)??)??)?:((\d{4})(-(\d{2}))??(-(\d{2}))??(T(\d{2}):(\d{2})(:(\d{2}))??(\.(\d+))??(([\+\-]{1}\d{2}:\d{2})&#124;Z)??)??)?$
"2017-12-01T00:00:00Z:2017-12-31T00:00:00Z"
filter:users string Comma separated list of user ids 123

Curl Example

$ curl -n https://api.battlemetrics.com/organizations/$ORGANIZATION_ID/relationships/command-stats
 -G \
  -d filter[summary]=true \
  -d filter[users]=123 \
  -d filter[commands]=addBMBan%2Craw \
  -d filter[timestamp]=2017-12-01T00%3A00%3A00Z%3A2017-12-31T00%3A00%3A00Z \
  -d filter[servers]=example

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "id": "1:1",
      "type": "commandStats",
      "attributes": {
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organization",
            "id": "42"
          }
        },
        "games": {
          "data": [
            {
              "type": "game",
              "id": "ark"
            }
          ]
        },
        "user": {
          "data": {
            "type": "user",
            "id": "42"
          }
        }
      }
    }
  ]
}

Coplay

Stability: prototype

The time two players have spent together.

Attributes

Name Type Description Example
attributes:duration integer Time played together in seconds. 42
attributes:name string The most recent name the player was seen using "Quark"
id string unique identifier of player
pattern: \d+
"42"
type string Resource type. Always "coplayRelation"
one of:"coplayRelation"
"coplayRelation"

List of time spent with other players.

GET /players/{player_id}/relationships/coplay

Required Parameters

Name Type Description Example
filter:organizations string Filter result to specific organizations. Comma-separated values. "example"
filter:period string Time range. The start of the range is required and must be within 30 days of the current date.
pattern: ^((\d{4})(-(\d{2}))??(-(\d{2}))??(T(\d{2}):(\d{2})(:(\d{2}))??(\.(\d+))??(([\+\-]{1}\d{2}:\d{2})&#124;Z)??)??)?:((\d{4})(-(\d{2}))??(-(\d{2}))??(T(\d{2}):(\d{2})(:(\d{2}))??(\.(\d+))??(([\+\-]{1}\d{2}:\d{2})&#124;Z)??)??)?$
"2017-12-01T00:00:00Z:2017-12-31T00:00:00Z"
filter:players string Filter result to specific players. Comma-separated values. "example"
filter:servers string Filter result to specific servers. Comma-separated values. "example"

Optional Parameters

Name Type Description Example
fields:coplayRelation string Request that only some attributes are returned "name,duration"
page:key string Page key "100,100"
page:offset integer Page offset
Range: 0 <= value <= 100
"10"
page:rel string Direction. Next/prev records based on key.
one of:"next" or "prev"
"next"
page:size integer Number of records to return per page
default: 10
Range: 1 <= value <= 100
42

Curl Example

$ curl -n https://api.battlemetrics.com/players/$PLAYER_ID/relationships/coplay
 -G \
  -d filter[period]=2017-12-01T00%3A00%3A00Z%3A2017-12-31T00%3A00%3A00Z \
  -d filter[players]=example \
  -d filter[servers]=example \
  -d filter[organizations]=example \
  -d page[size]=42 \
  -d page[key]=100%2C100 \
  -d page[offset]=10 \
  -d page[rel]=next \
  -d fields[coplayRelation]=name%2Cduration

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "type": "coplayRelation",
      "id": "42",
      "attributes": {
        "name": "Quark",
        "duration": 42
      }
    }
  ],
  "links": {
    "next": "https://api.battlemetrics.com/players/1/relationships/coplay?page[size]=10&page[offset]=10",
    "prev": "https://api.battlemetrics.com/players/1/relationships/coplay?page[size]=10&page[offset]=0"
  }
}

Data Point

Stability: prototype

A data point as used in time series information.

Attributes

Name Type Description Example
attributes:group number When requesting multiple groups of metrics this will be the index of the corresponding request. 0
attributes:max integer Maximum point value 42
attributes:min integer Minimum point value 42
attributes:name string Name of the metric that the data point is for. Will only be present when more than one metric is being returned. "games.arma3.players"
attributes:timestamp date-time Data point timestamp "2015-01-01T12:00:00Z"
attributes:value integer Data point value 42
type string Resource type. Always "dataPoint"
one of:"dataPoint"
"dataPoint"

Get data points for one or more metrics

GET /metrics

Required Parameters

Name Type Description Example
metrics/name string Name of the metric. Multiple metrics may be requested by separating names with a comma. "games.arma3.players,games.arma3.players.steam"
metrics/range string Requested time range. Beginning and ending timestamps required. Format: ISO8601:ISO8601
pattern: ^((\d{4})(-(\d{2}))??(-(\d{2}))??(T(\d{2}):(\d{2})(:(\d{2}))??(\.(\d+))??(([\+\-]{1}\d{2}:\d{2})&#124;Z)??)??):((\d{4})(-(\d{2}))??(-(\d{2}))??(T(\d{2}):(\d{2})(:(\d{2}))??(\.(\d+))??(([\+\-]{1}\d{2}:\d{2})&#124;Z)??)??)$
"2017-12-01T00:00:00Z:2017-12-31T00:00:00Z"
metrics/resolution string Data resolution
one of:"raw" or "30" or "60" or "1440"
"60"

Optional Parameters

Name Type Description Example
fields:dataPoint string Request that only some attributes are returned "value"

Curl Example

$ curl -n https://api.battlemetrics.com/metrics
 -G \
  -d fields[dataPoint]=value \
  -d metrics[]=%7B%22name%22%3D%3E%22games.arma3.players%2Cgames.arma3.players.steam%22%2C+%22range%22%3D%3E%222017-12-01T00%3A00%3A00Z%3A2017-12-31T00%3A00%3A00Z%22%2C+%22resolution%22%3D%3E%2260%22%7D

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "type": "dataPoint",
      "attributes": {
        "timestamp": "2015-01-01T12:00:00Z",
        "group": 0,
        "name": "games.arma3.players",
        "max": 42,
        "value": 42,
        "min": 42
      }
    }
  ]
}

Flag Player

Stability: prototype

Flagged Player. The relationship between a player flag and a player. Has information about when it was added and when/if it's been removed. Requires flag:read scope to view.

Attributes

Name Type Description Example
attributes:addedAt date-time When the flag was added to the player "2015-01-01T12:00:00Z"
attributes:removedAt nullable date-time When the flag was removed from the player null
id string unique identifier of flagged player "example"
relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
relationships:player:data:id string unique identifier of player
pattern: \d+
"42"
relationships:player:data:type string Resource type. Always "player"
one of:"player"
"player"
relationships:playerFlag:data:id uuid unique identifier of player flag "01234567-89ab-cdef-0123-456789abcdef"
relationships:playerFlag:data:type string Resource type. Always playerFlag.
one of:"playerFlag"
"playerFlag"
relationships:user:data:id string unique identifier of user
pattern: \d+
"42"
relationships:user:data:type string Resource type. Always "user"
one of:"user"
"user"
type string Resource type. Always flagPlayer.
one of:"flagPlayer"
"flagPlayer"

Flag Player Create

Add a flag to a player

POST /players/{player_id}/relationships/flags

Optional Parameters

Name Type Description Example
data/id uuid unique identifier of player flag "01234567-89ab-cdef-0123-456789abcdef"
data/type string Resource type. Always playerFlag.
one of:"playerFlag"
"playerFlag"

Curl Example

$ curl -n -X POST https://api.battlemetrics.com/players/$PLAYER_ID/relationships/flags \
  -d '{
  "data": [
    {
      "type": "playerFlag",
      "id": "01234567-89ab-cdef-0123-456789abcdef"
    }
  ]
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 201 Created
{
  "data": [
    {
      "id": "example",
      "type": "flagPlayer",
      "attributes": {
        "addedAt": "2015-01-01T12:00:00Z",
        "removedAt": "2015-01-01T12:00:00Z"
      },
      "relationships": {
        "playerFlag": {
          "data": {
            "type": "playerFlag",
            "id": "01234567-89ab-cdef-0123-456789abcdef"
          }
        },
        "player": {
          "data": {
            "type": "player",
            "id": "42"
          }
        },
        "user": {
          "data": {
            "type": "user",
            "id": "42"
          }
        },
        "organization": {
          "data": {
            "type": "organization",
            "id": "42"
          }
        }
      }
    }
  ]
}

List flags that have been added to a player

GET /players/{player_id}/relationships/flags

Optional Parameters

Name Type Description Example
include string Relations to include. Comma separated. Valid: playerFlag, organization "playerFlag"
page:key string Page key. The value to start from. The prev and next links provide this value automatically. It's recommended that you don't manually provide this value. "100"
page:rel string Direction. Next/prev records based on key.
one of:"next" or "prev"
"next"
page:size integer Number of items to return per page
default: 10
Range: 1 <= value <= 100
42

Curl Example

$ curl -n https://api.battlemetrics.com/players/$PLAYER_ID/relationships/flags
 -G \
  -d include=playerFlag \
  -d page[size]=42 \
  -d page[key]=100 \
  -d page[rel]=next

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "id": "example",
      "type": "flagPlayer",
      "attributes": {
        "addedAt": "2015-01-01T12:00:00Z",
        "removedAt": "2015-01-01T12:00:00Z"
      },
      "relationships": {
        "playerFlag": {
          "data": {
            "type": "playerFlag",
            "id": "01234567-89ab-cdef-0123-456789abcdef"
          }
        },
        "player": {
          "data": {
            "type": "player",
            "id": "42"
          }
        },
        "user": {
          "data": {
            "type": "user",
            "id": "42"
          }
        },
        "organization": {
          "data": {
            "type": "organization",
            "id": "42"
          }
        }
      }
    }
  ],
  "included": [

  ],
  "links": {
    "next": "https://api.battlemetrics.com/players/1/relationships/flags",
    "prev": "https://api.battlemetrics.com/players/1/relationships/flags"
  }
}

Delete an existing flag.

DELETE /players/{player_id}/relationships/flags/{playerFlag_id}

Curl Example

$ curl -n -X DELETE https://api.battlemetrics.com/players/$PLAYER_ID/relationships/flags/$PLAYERFLAG_ID \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 200 OK
{
  "data": {
    "id": "example",
    "type": "flagPlayer",
    "attributes": {
      "addedAt": "2015-01-01T12:00:00Z",
      "removedAt": "2015-01-01T12:00:00Z"
    },
    "relationships": {
      "playerFlag": {
        "data": {
          "type": "playerFlag",
          "id": "01234567-89ab-cdef-0123-456789abcdef"
        }
      },
      "player": {
        "data": {
          "type": "player",
          "id": "42"
        }
      },
      "user": {
        "data": {
          "type": "user",
          "id": "42"
        }
      },
      "organization": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      }
    }
  }
}

Game

Stability: prototype

Information about games supported by BattleMetrics

Attributes

Name Type Description Example
attributes:maxPlayers24H number Maximum number of players seen in the past 24 hours 42.0
attributes:maxPlayers30D number Maximum number of players seen in the past 30 days 42.0
attributes:maxPlayers7D number Maximum number of players seen in the past 7 days 42.0
attributes:metadata:appid number Steam app id 42.0
attributes:metadata:gamedir string Steam game directory used in queries "example"
attributes:metadata:noPlayerList boolean True if we are unable to provide public player lists for the game. true
attributes:minPlayers24H number Minimum number of players seen in the past 24 hours 42.0
attributes:minPlayers30D number Minimum number of players seen in the past 30 days 42.0
attributes:minPlayers7D number Minimum number of players seen in the past 7 days 42.0
attributes:name string Long name for game. "ARK: Survival Evolved"
attributes:players number Number of players currently online 300
attributes:playersByCountry object The number of players per country. Keys are ISO 3166-1 alpha-2 country codes, values are the number of servers. If a country is omitted it has no players. {"US":100,"CA":100,"GB":100}
attributes:servers number Number of servers currently online 300
attributes:serversByCountry object The number of servers per country. Keys are ISO 3166-1 alpha-2 country codes, values are the number of servers. If a country is omitted it has no servers. {"US":100,"CA":100,"GB":100}
id string unique identifier of game
pattern: [a-z0-9]+
"ark"
type string Resource type. Always "game"
one of:"game"
"game"

List games

GET /games

Optional Parameters

Name Type Description Example
fields:game string Request that only some attributes are returned "name"
page:key string Page key "100"
page:rel string Direction. Next/prev records based on key.
one of:"next" or "prev"
"next"
page:size integer Number of items to return per page
default: 100
Range: 1 <= value <= 100
42

Curl Example

$ curl -n https://api.battlemetrics.com/games
 -G \
  -d page[size]=42 \
  -d page[key]=100 \
  -d page[rel]=next \
  -d fields[game]=name

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "id": "ark",
      "type": "game",
      "attributes": {
        "name": "ARK: Survival Evolved",
        "metadata": {
          "appid": 42.0,
          "gamedir": "example",
          "noPlayerList": true
        },
        "players": 300,
        "servers": 300,
        "serversByCountry": {
          "US": 100,
          "CA": 100,
          "GB": 100
        },
        "playersByCountry": {
          "US": 100,
          "CA": 100,
          "GB": 100
        },
        "maxPlayers30D": 42.0,
        "maxPlayers7D": 42.0,
        "maxPlayers24H": 42.0,
        "minPlayers30D": 42.0,
        "minPlayers7D": 42.0,
        "minPlayers24H": 42.0
      }
    }
  ],
  "links": {
    "next": "https://api.battlemetrics.com/games?page[size]=10&page[key]=fa06c3f2-c68e-11e7-8fd0-2bafd001f0f8&page[rel]=next",
    "prev": "https://api.battlemetrics.com/games?page[size]=10&page[key]=fa06c3f2-c68e-11e7-8fd0-2bafd001f0f8&page[rel]=prev"
  }
}

Details on a single game

GET /games/{game_id}

Optional Parameters

Name Type Description Example
fields:game string Request that only some attributes are returned "name"

Curl Example

$ curl -n https://api.battlemetrics.com/games/$GAME_ID
 -G \
  -d fields[game]=name

Response Example

HTTP/2.0 200 OK
{
  "data": {
    "id": "ark",
    "type": "game",
    "attributes": {
      "name": "ARK: Survival Evolved",
      "metadata": {
        "appid": 42.0,
        "gamedir": "example",
        "noPlayerList": true
      },
      "players": 300,
      "servers": 300,
      "serversByCountry": {
        "US": 100,
        "CA": 100,
        "GB": 100
      },
      "playersByCountry": {
        "US": 100,
        "CA": 100,
        "GB": 100
      },
      "maxPlayers30D": 42.0,
      "maxPlayers7D": 42.0,
      "maxPlayers24H": 42.0,
      "minPlayers30D": 42.0,
      "minPlayers7D": 42.0,
      "minPlayers24H": 42.0
    }
  }
}

Game Features

Stability: prototype

Game features can be used with the server list filters to search for specific server options and details.

Attributes

Name Type Description Example
attributes:display string Display name of this feature "Map"
attributes:featureType string Feature type
one of:"select" or "boolean" or "range" or "dateRange"
"select"
attributes:typeOptions string
id uuid unique identifier of the feature "01234567-89ab-cdef-0123-456789abcdef"
relationships:game:data:id string unique identifier of game
pattern: [a-z0-9]+
"ark"
relationships:game:data:type string Resource type. Always "game"
one of:"game"
"game"
type string Resource type. Always "gameFeature"
one of:"gameFeature"
"gameFeature"

List game features

GET /game-features

Optional Parameters

Name Type Description Example
fields:gameFeature string Request that only some attributes are returned "display"
filter:game string Filter features by game. "example"
page:key string Page key "100"
page:rel string Direction. Next/prev records based on key.
one of:"next" or "prev"
"next"
page:size integer Number of items to return per page
default: 10
Range: 1 <= value <= 100
42

Curl Example

$ curl -n https://api.battlemetrics.com/game-features
 -G \
  -d filter[game]=example \
  -d page[size]=42 \
  -d page[key]=100 \
  -d page[rel]=next \
  -d fields[gameFeature]=display

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "type": "gameFeature",
      "attributes": {
        "display": "Map",
        "featureType": "select",
        "typeOptions": {
          "allowMultiple": true,
          "boolMode": "or"
        }
      },
      "relationships": {
        "game": {
          "data": {
            "type": "game",
            "id": "arma2"
          }
        }
      }
    }
  ],
  "links": {
    "next": "https://api.battlemetrics.com/game-features?page[size]=10&page[key]=fa06c3f2-c68e-11e7-8fd0-2bafd001f0f8&page[rel]=next",
    "prev": "https://api.battlemetrics.com/game-features?page[size]=10&page[key]=fa06c3f2-c68e-11e7-8fd0-2bafd001f0f8&page[rel]=prev"
  }
}

Game Feature Options

Stability: prototype

Game feature options are the options available for a select type game option. An option maps a display value to one or more values that we will search for on servers.

Attributes

Name Type Description Example
attributes:count integer The total number of servers that match this option. 100
attributes:display string Display name of this option "Chernarus"
attributes:players integer The total number of players that are playing on servers that match this option. 1000
attributes:updatedAt date-time The last time the option was updated "2015-01-01T12:00:00Z"
id uuid unique identifier of the option "01234567-89ab-cdef-0123-456789abcdef"
relationships:gameFeature:data:id uuid unique identifier of the feature "01234567-89ab-cdef-0123-456789abcdef"
relationships:gameFeature:data:type string Resource type. Always "gameFeature"
one of:"gameFeature"
"gameFeature"
type string Resource type. Always "gameFeatureOption"
one of:"gameFeatureOption"
"gameFeatureOption"

List game feature options

GET /game-features/{gameFeature_id}/relationships/options

Optional Parameters

Name Type Description Example
fields:gameFeatureOption string Request that only some attributes are returned "display,count"
filter:count string Filter options by count.
default: "10:"
pattern: ^(\d+)?:(\d+)?$
"10:"
filter:players string Filter options by players.
default: "10:"
pattern: ^(\d+)?:(\d+)?$
"10:"
page:key string Page key "100"
page:rel string Direction. Next/prev records based on key.
one of:"next" or "prev"
"next"
page:size integer Number of items to return per page
default: 10
Range: 1 <= value <= 500
42
sort string Sorting options. Valid options: count, players
default: "count"
"example"

Curl Example

$ curl -n https://api.battlemetrics.com/game-features/$GAMEFEATURE_ID/relationships/options
 -G \
  -d filter[count]=10%3A \
  -d filter[players]=10%3A \
  -d sort=example \
  -d page[size]=42 \
  -d page[key]=100 \
  -d page[rel]=next \
  -d fields[gameFeatureOption]=display%2Ccount

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "type": "gameFeatureOption",
      "attributes": {
        "display": "Chernarus",
        "updatedAt": "2015-01-01T12:00:00Z",
        "count": 100,
        "players": 1000
      },
      "relationships": {
        "gameFeature": {
          "data": {
            "type": "gameFeature",
            "id": "01234567-89ab-cdef-0123-456789abcdef"
          }
        }
      }
    }
  ],
  "links": {
    "next": "https://api.battlemetrics.com/game-features/fa06c3f2-c68e-11e7-8fd0-2bafd001f0f8/relationships/options?page[size]=10&page[key]=8aea2b84-c68f-11e7-8446-6bb42537a5a8&page[rel]=next",
    "prev": "https://api.battlemetrics.com/game-features/fa06c3f2-c68e-11e7-8fd0-2bafd001f0f8/relationships/options?page[size]=10&page[key]=8aea2b84-c68f-11e7-8446-6bb42537a5a8&page[rel]=prev"
  }
}

Player Identifier

Stability: prototype

A Player identifier. For Example a Steam ID, or BattlEye GUID

Attributes

Name Type Description Example
attributes:identifier string The Identifier "76561197960265720"
attributes:lastSeen date-time The last time we saw the identifier. "2015-01-01T12:00:00Z"
attributes:metadata nullable object Extra information about the identifier. The information available will vary. null
attributes:private boolean If the identifier should be considered private. true
attributes:type string Identifier type
one of:"steamID" or "BEGUID" or "legacyBEGUID" or "ip" or "name" or "survivorName" or "steamFamilyShareOwner" or "conanCharName" or "egsID" or "eosID" or "funcomID" or "playFabID" or "mcUUID" or "7dtdEOS" or "battlebitHWID" or "hllWindowsID" or "palworldUID"
"steamID"
id string Identifier ID
pattern: \d+
"example"
relationships:organizations:data/id string unique identifier of organization
pattern: \d+
"42"
relationships:organizations:data/type string Resource type. Always "organization"
one of:"organization"
"organization"
relationships:player:data:id string unique identifier of player
pattern: \d+
"42"
relationships:player:data:type string Resource type. Always "player"
one of:"player"
"player"
type string Resource type. Always "identifier"
one of:"identifier"
"identifier"

Leaderboard

Stability: prototype

Leaderboards

Attributes

Name Type Description Example
attributes:name string The most recent name the player was seen using "Quark"
attributes:rank integer Players position in the leaderboard. 42
attributes:value integer Time played in seconds. 42
id string unique identifier of player
pattern: \d+
"42"
type string Resource type. Always "leaderboardPlayer"
one of:"leaderboardPlayer"
"leaderboardPlayer"

Leaderboard for time played.

GET /servers/{server_id}/relationships/leaderboards/time

Required Parameters

Name Type Description Example
filter:period string Leaderboard time period. Should be AT (All Time) or a time period in the format 2017-12-01T00:00:00Z:2017-12-31T00:00:00Z. Timestamps should be in ISO-8601 format. "AT"
filter:player integer Filter result to a single player. 42

Optional Parameters

Name Type Description Example
fields:leaderboardPlayer string Request that only some attributes are returned "name,value"
page:key string Page key "100,100"
page:offset integer Page offset
Range: 0 <= value <= 1000
"50"
page:rel string Direction. Next/prev records based on key.
one of:"next" or "prev"
"next"
page:size integer Number of records to return per page
default: 10
Range: 1 <= value <= 100
42

Curl Example

$ curl -n https://api.battlemetrics.com/servers/$SERVER_ID/relationships/leaderboards/time
 -G \
  -d filter[period]=AT \
  -d filter[player]=42 \
  -d page[size]=42 \
  -d page[key]=100%2C100 \
  -d page[offset]=50 \
  -d page[rel]=next \
  -d fields[leaderboardPlayer]=name%2Cvalue

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "type": "leaderboardPlayer",
      "id": "42",
      "attributes": {
        "name": "Quark",
        "value": 42,
        "rank": 42
      }
    }
  ],
  "links": {
    "next": "https://api.battlemetrics.com/servers/1/leaderboards/time?page[size]=10&page[offset]=10",
    "prev": "https://api.battlemetrics.com/servers/1/leaderboards/time?page[size]=10&page[offset]=0"
  }
}

Organization

Stability: prototype

Organization

Attributes

Name Type Description Example
attributes:active boolean If the organization is active. Active organizations have either a server through a partnered GSP, or an organization owner with an active subscription/trial. Only visible to users who belong to the organization. true
attributes:banTemplate string Ban template used as the default when creating a ban. See Ban Templates. "{{uid}} - {{duration}} ({{admin}})"
attributes:consentGeoIPRequired boolean When true organization members will be required to consent to sharing their GeoIP information with the organization. true
attributes:discoverable boolean If the organization should be made discoverable to other users/organizations. true
attributes:discoverableRank nullable integer A minimum required rank required before the organization will be visible to other organizations. true
attributes:locale nullable string Locale used when formatting dates and times. Currently only used for ban reasons. "en"
attributes:mfaRequired nullable date-time MFA requirement for the organization. null
attributes:name string The name of the organization "Bajor"
attributes:plan nullable string Subscription type "rcon_monthly"
attributes:tz nullable string Currently only used for ban reasons. "America/Los_Angeles"
id string unique identifier of organization
pattern: \d+
"42"
relationships:banLists:data/id uuid Ban ID "01234567-89ab-cdef-0123-456789abcdef"
relationships:banLists:data/type string Resource type. Always banList.
one of:"banList"
"banList"
relationships:defaultBanList:data nullable object null
relationships:defaultBanList:data:id uuid Ban ID "01234567-89ab-cdef-0123-456789abcdef"
relationships:defaultBanList:data:type string Resource type. Always banList.
one of:"banList"
"banList"
relationships:games:data/id string unique identifier of game
pattern: [a-z0-9]+
"ark"
relationships:games:data/type string Resource type. Always "game"
one of:"game"
"game"
relationships:owner:data:id string unique identifier of user
pattern: \d+
"42"
relationships:owner:data:type string Resource type. Always "user"
one of:"user"
"user"
relationships:servers:data/id string unique identifier of server
pattern: \d+
"42"
relationships:servers:data/type string Resource type. Always "server"
one of:"server"
"server"
type string Resource type. Always "organization"
one of:"organization"
"organization"

Get players stats for the organization

GET /organizations/{organization_id}/stats/players

Required Parameters

Name Type Description Example
filter:range string Requested range. Start must be within 90 days.
pattern: ^((\d{4})(-(\d{2}))??(-(\d{2}))??(T(\d{2}):(\d{2})(:(\d{2}))??(\.(\d+))??(([\+\-]{1}\d{2}:\d{2})&#124;Z)??)??):((\d{4})(-(\d{2}))??(-(\d{2}))??(T(\d{2}):(\d{2})(:(\d{2}))??(\.(\d+))??(([\+\-]{1}\d{2}:\d{2})&#124;Z)??)??)$
"example"

Optional Parameters

Name Type Description Example
fields:playerStats string Request that only some attributes are returned "uniquePlayers"
filter:game string Filter stats by game "rust"
filter:group uuid Filter stats by organization group id "01234567-89ab-cdef-0123-456789abcdef"

Curl Example

$ curl -n https://api.battlemetrics.com/organizations/$ORGANIZATION_ID/stats/players
 -G \
  -d fields[playerStats]=uniquePlayers \
  -d filter[game]=rust \
  -d filter[group]=01234567-89ab-cdef-0123-456789abcdef \
  -d filter[range]=example

Response Example

HTTP/2.0 200 OK
{
  "data": {
    "type": "playerStats",
    "attributes": {
      "uniquePlayers": 42.0,
      "minPlayers": 42.0,
      "maxPlayers": 42.0,
      "uniquePlayersByCountry": {
        "US": 100,
        "CA": 50,
        "unknown": 25
      },
      "sessionDuration": 42.0,
      "firstTimeSessionDuration": 42.0
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      },
      "server": {
        "data": {
          "type": "server",
          "id": "42"
        }
      },
      "game": {
        "data": {
          "type": "game",
          "id": "ark"
        }
      },
      "orgGroup": {
        "data": {
          "type": "orgGroup",
          "id": "01234567-89ab-cdef-0123-456789abcdef"
        }
      }
    }
  }
}

Organization Friend

Stability: prototype

Organization data sharing arrangement.

Attributes

Name Type Description Example
attributes:accepted boolean If the offer has been accepted. true
attributes:identifiers nullable array Identifier types shared ["ip","steamID"]
attributes:identifiers nullable array Identifier types shared ["ip","steamID"]
attributes:notes boolean If notes are shared true
attributes:reciprocated boolean True if both sides of the organization friendship are sharing data. true
id string unique identifier of organizationFriend "1:2"
relationships:flagsShared:data/id uuid unique identifier of player flag "01234567-89ab-cdef-0123-456789abcdef"
relationships:flagsShared:data/type string Resource type. Always playerFlag.
one of:"playerFlag"
"playerFlag"
relationships:flagsUsed:data/id uuid unique identifier of player flag "01234567-89ab-cdef-0123-456789abcdef"
relationships:flagsUsed:data/type string Resource type. Always playerFlag.
one of:"playerFlag"
"playerFlag"
relationships:friend:data:id string unique identifier of organization
pattern: \d+
"42"
relationships:friend:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
type string Resource type. Always "organizationFriend"
one of:"organizationFriend"
"organizationFriend"

List Friends

GET /organizations/{organization_id}/relationships/friends

Optional Parameters

Name Type Description Example
fields:organization string Request that only some attributes are returned "tz,banTemplate"
fields:organizationFriend string Request that only some attributes are returned "identifiers,notes"
filter:accepted boolean Filter friends by if they have accepted or not. true
filter:name string Filter relationships by organization name. "example"
filter:origin boolean Filter relationships by who created them. true
filter:reciprocated boolean Filter relationships by if they are reciprocated or not. true
include string Relations to include. Comma separated. "organization"
page:key string Page key. The value to start from. The prev and next links provide this value automatically. It's recommended that you don't manually provide this value. "100"
page:rel string Direction. Next/prev records based on key.
one of:"next" or "prev"
"next"
page:size integer Number of items to return per page
default: 10
Range: 1 <= value <= 100
42
sort string Sorting options. Default is name. Valid options: name, rank "example"

Curl Example

$ curl -n https://api.battlemetrics.com/organizations/$ORGANIZATION_ID/relationships/friends
 -G \
  -d sort=example \
  -d page[size]=42 \
  -d page[key]=100 \
  -d page[rel]=next \
  -d fields[organizationFriend]=identifiers%2Cnotes \
  -d fields[organization]=tz%2CbanTemplate \
  -d filter[accepted]=true \
  -d filter[origin]=true \
  -d filter[reciprocated]=true \
  -d filter[name]=example \
  -d include=organization

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "id": "1:2",
      "type": "organizationFriend",
      "attributes": {
        "accepted": true,
        "identifiers": [
          "ip",
          "steamID"
        ],
        "notes": true,
        "reciprocated": true
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organization",
            "id": "42"
          }
        },
        "friend": {
          "data": {
            "type": "organization",
            "id": "42"
          }
        },
        "flagsShared": {
          "data": [
            {
              "type": "playerFlag",
              "id": "01234567-89ab-cdef-0123-456789abcdef"
            }
          ]
        },
        "flagsUsed": {
          "data": [
            {
              "type": "playerFlag",
              "id": "01234567-89ab-cdef-0123-456789abcdef"
            }
          ]
        }
      }
    }
  ],
  "included": [

  ],
  "links": {
    "next": "example",
    "prev": "example"
  }
}

Get organization friend relationship

GET /organizations/{organization_id}/relationships/friends/{organization_id}

Optional Parameters

Name Type Description Example
fields:organization string Request that only some attributes are returned "tz,banTemplate"
fields:organizationFriend string Request that only some attributes are returned "identifiers,notes"
fields:playerFlag string Request that only some attributes are returned "updatedAt,name"
include string Relations to include. Comma separated. "organization,playerFlag,organizationStats"

Curl Example

$ curl -n https://api.battlemetrics.com/organizations/$ORGANIZATION_ID/relationships/friends/$ORGANIZATION_ID
 -G \
  -d fields[organizationFriend]=identifiers%2Cnotes \
  -d fields[organization]=tz%2CbanTemplate \
  -d fields[playerFlag]=updatedAt%2Cname \
  -d include=organization%2CplayerFlag%2CorganizationStats

Response Example

HTTP/2.0 200 OK
{
  "data": {
    "id": "1:2",
    "type": "organizationFriend",
    "attributes": {
      "accepted": true,
      "identifiers": [
        "ip",
        "steamID"
      ],
      "notes": true,
      "reciprocated": true
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      },
      "friend": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      },
      "flagsShared": {
        "data": [
          {
            "type": "playerFlag",
            "id": "01234567-89ab-cdef-0123-456789abcdef"
          }
        ]
      },
      "flagsUsed": {
        "data": [
          {
            "type": "playerFlag",
            "id": "01234567-89ab-cdef-0123-456789abcdef"
          }
        ]
      }
    }
  },
  "included": [

  ]
}

Update relationship settings

PATCH /organizations/{organization_id}/relationships/friends/{organization_id}

Required Parameters

Name Type Description Example
data:attributes:accepted boolean If the offer has been accepted. true
data:attributes:identifiers nullable array Identifier types shared ["ip","steamID"]
data:attributes:identifiers nullable array Identifier types shared ["ip","steamID"]
data:attributes:notes boolean If notes are shared true
data:id string unique identifier of organizationFriend "1:2"
data:relationships:flagsShared:data/id uuid unique identifier of player flag "01234567-89ab-cdef-0123-456789abcdef"
data:relationships:flagsShared:data/type string Resource type. Always playerFlag.
one of:"playerFlag"
"playerFlag"
data:relationships:flagsUsed:data/id uuid unique identifier of player flag "01234567-89ab-cdef-0123-456789abcdef"
data:relationships:flagsUsed:data/type string Resource type. Always playerFlag.
one of:"playerFlag"
"playerFlag"
data:type string Resource type. Always "organizationFriend"
one of:"organizationFriend"
"organizationFriend"

Curl Example

$ curl -n -X PATCH https://api.battlemetrics.com/organizations/$ORGANIZATION_ID/relationships/friends/$ORGANIZATION_ID \
  -d '{
  "data": {
    "id": "1:2",
    "type": "organizationFriend",
    "attributes": {
      "accepted": true,
      "identifiers": [
        "ip",
        "steamID"
      ],
      "notes": true
    },
    "relationships": {
      "flagsUsed": {
        "data": [
          {
            "type": "playerFlag",
            "id": "01234567-89ab-cdef-0123-456789abcdef"
          }
        ]
      },
      "flagsShared": {
        "data": [
          {
            "type": "playerFlag",
            "id": "01234567-89ab-cdef-0123-456789abcdef"
          }
        ]
      }
    }
  }
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 200 OK
{
  "data": {
    "id": "1:2",
    "type": "organizationFriend",
    "attributes": {
      "accepted": true,
      "identifiers": [
        "ip",
        "steamID"
      ],
      "notes": true,
      "reciprocated": true
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      },
      "friend": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      },
      "flagsShared": {
        "data": [
          {
            "type": "playerFlag",
            "id": "01234567-89ab-cdef-0123-456789abcdef"
          }
        ]
      },
      "flagsUsed": {
        "data": [
          {
            "type": "playerFlag",
            "id": "01234567-89ab-cdef-0123-456789abcdef"
          }
        ]
      }
    }
  }
}

Bulk update relationship settings

PATCH /organizations/{organization_id}/relationships/friends/{organization_id}

Required Parameters

Name Type Description Example
data/attributes:accepted boolean If the offer has been accepted. true
data/attributes:identifiers nullable array Identifier types shared ["ip","steamID"]
data/attributes:identifiers nullable array Identifier types shared ["ip","steamID"]
data/attributes:notes boolean If notes are shared true
data/id string unique identifier of organizationFriend "1:2"
data/relationships:flagsShared:data/id uuid unique identifier of player flag "01234567-89ab-cdef-0123-456789abcdef"
data/relationships:flagsShared:data/type string Resource type. Always playerFlag.
one of:"playerFlag"
"playerFlag"
data/relationships:flagsUsed:data/id uuid unique identifier of player flag "01234567-89ab-cdef-0123-456789abcdef"
data/relationships:flagsUsed:data/type string Resource type. Always playerFlag.
one of:"playerFlag"
"playerFlag"
data/type string Resource type. Always "organizationFriend"
one of:"organizationFriend"
"organizationFriend"

Curl Example

$ curl -n -X PATCH https://api.battlemetrics.com/organizations/$ORGANIZATION_ID/relationships/friends/$ORGANIZATION_ID \
  -d '{
  "data": [
    {
      "id": "1:2",
      "type": "organizationFriend",
      "attributes": {
        "accepted": true,
        "identifiers": [
          "ip",
          "steamID"
        ],
        "notes": true
      },
      "relationships": {
        "flagsUsed": {
          "data": [
            {
              "type": "playerFlag",
              "id": "01234567-89ab-cdef-0123-456789abcdef"
            }
          ]
        },
        "flagsShared": {
          "data": [
            {
              "type": "playerFlag",
              "id": "01234567-89ab-cdef-0123-456789abcdef"
            }
          ]
        }
      }
    }
  ]
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "id": "1:2",
      "type": "organizationFriend",
      "attributes": {
        "accepted": true,
        "identifiers": [
          "ip",
          "steamID"
        ],
        "notes": true,
        "reciprocated": true
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organization",
            "id": "42"
          }
        },
        "friend": {
          "data": {
            "type": "organization",
            "id": "42"
          }
        },
        "flagsShared": {
          "data": [
            {
              "type": "playerFlag",
              "id": "01234567-89ab-cdef-0123-456789abcdef"
            }
          ]
        },
        "flagsUsed": {
          "data": [
            {
              "type": "playerFlag",
              "id": "01234567-89ab-cdef-0123-456789abcdef"
            }
          ]
        }
      }
    }
  ]
}

Organization Friend Create

Create a new organization friend

POST /organizations/{organization_id}/relationships/friends

Required Parameters

Name Type Description Example
data:attributes:identifiers nullable array Identifier types shared ["ip","steamID"]
data:attributes:identifiers nullable array Identifier types shared ["ip","steamID"]
data:attributes:notes boolean If notes are shared true
data:relationships:flagsShared:data/id uuid unique identifier of player flag "01234567-89ab-cdef-0123-456789abcdef"
data:relationships:flagsShared:data/type string Resource type. Always playerFlag.
one of:"playerFlag"
"playerFlag"
data:relationships:friend:data:id string unique identifier of organization
pattern: \d+
"42"
data:relationships:friend:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
data:type string Resource type. Always "organizationFriend"
one of:"organizationFriend"
"organizationFriend"

Curl Example

$ curl -n -X POST https://api.battlemetrics.com/organizations/$ORGANIZATION_ID/relationships/friends \
  -d '{
  "data": {
    "type": "organizationFriend",
    "attributes": {
      "identifiers": [
        "ip",
        "steamID"
      ],
      "notes": true
    },
    "relationships": {
      "friend": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      },
      "flagsShared": {
        "data": [
          {
            "type": "playerFlag",
            "id": "01234567-89ab-cdef-0123-456789abcdef"
          }
        ]
      }
    }
  }
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 201 Created
{
  "data": {
    "id": "1:2",
    "type": "organizationFriend",
    "attributes": {
      "accepted": true,
      "identifiers": [
        "ip",
        "steamID"
      ],
      "notes": true,
      "reciprocated": true
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      },
      "friend": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      },
      "flagsShared": {
        "data": [
          {
            "type": "playerFlag",
            "id": "01234567-89ab-cdef-0123-456789abcdef"
          }
        ]
      },
      "flagsUsed": {
        "data": [
          {
            "type": "playerFlag",
            "id": "01234567-89ab-cdef-0123-456789abcdef"
          }
        ]
      }
    }
  }
}

Delete an existing organizationFriend.

DELETE /organizations/{organization_id}/relationships/friends/{organization_id}

Curl Example

$ curl -n -X DELETE https://api.battlemetrics.com/organizations/$ORGANIZATION_ID/relationships/friends/$ORGANIZATION_ID \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 204 No Content

Bulk delete organizationFriend relationships.

DELETE /organizations/{organization_id}/relationships/friends

Required Parameters

Name Type Description Example
data/id string unique identifier of organizationFriend "1:2"
data/type string Resource type. Always "organizationFriend"
one of:"organizationFriend"
"organizationFriend"

Curl Example

$ curl -n -X DELETE https://api.battlemetrics.com/organizations/$ORGANIZATION_ID/relationships/friends \
  -d '{
  "data": [
    {
      "type": "organizationFriend",
      "id": "1:2"
    }
  ]
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 204 No Content

Organization Stats

Stability: prototype

Currently used to provide information about an organization in the organization discovery process and when accepting a data sharing request.

Attributes

Name Type Description Example
attributes:gameRanks object The top rank for each game the organization hosts. {"rust":100,"squad":50,"arma3":25}
attributes:identifiers number The total number of identifiers associated with the organization 42.0
attributes:uniquePlayers number The number of unique player ids in the past 90 days 42.0
id string unique identifier of organizationStats "example"
relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
type string Resource type. Always "organizationStats"
one of:"organizationStats"
"organizationStats"

Player

Stability: prototype

A player as seen on one or more servers.

The rcon:read scope is required to view and match private identifiers.

Attributes

Name Type Description Example
attributes:createdAt date-time when player was created "2015-01-01T12:00:00Z"
attributes:id string unique identifier of player
pattern: \d+
"42"
attributes:name string The most recent name the player was seen using "Quark"
attributes:positiveMatch boolean Players with positiveMatch set to true will only match with a guaranteed unique identifier. false
attributes:private boolean True if this is a private profile. Private profiles disable public profiles and remove the player from search and player lists. false
attributes:updatedAt date-time when player was last updated "2015-01-01T12:00:00Z"
id string unique identifier of player
pattern: \d+
"42"
meta:metadata/key string Metadata key, for example "ping", or "admin". "ping"
meta:metadata/private boolean True when the associated metadata is private. true
meta:metadata/value nullable string Metadata value. 100
relationships:organizations:data/id string unique identifier of organization
pattern: \d+
"42"
relationships:organizations:data/type string Resource type. Always "organization"
one of:"organization"
"organization"
relationships:server:data:id string unique identifier of server
pattern: \d+
"42"
relationships:server:data:type string Resource type. Always "server"
one of:"server"
"server"
relationships:servers:data/id string unique identifier of server
pattern: \d+
"42"
relationships:servers:data/meta:firstSeen date-time "2015-01-01T12:00:00Z"
relationships:servers:data/meta:lastSeen date-time "2015-01-01T12:00:00Z"
relationships:servers:data/meta:online boolean true
relationships:servers:data/meta:timePlayed integer Time played in seconds 42
relationships:servers:data/type string Resource type. Always "server"
one of:"server"
"server"
relationships:user:data:id string unique identifier of user
pattern: \d+
"42"
relationships:user:data:type string Resource type. Always "user"
one of:"user"
"user"
type string Resource type. Always "player"
one of:"player"
"player"

List, search and filter players.

When including servers with the results we will return a maximum of 100 servers. We will attempt to return the same number of servers for each player. If there are 10 players we would return the 10 most recent servers for each player.

If you use the filter[servers] option when including servers we will only return players that match that filter and only include those servers. The previously stated limits will still apply.

GET /players

Optional Parameters

Name Type Description Example
fields:flagPlayer string Request that only some attributes are returned "addedAt"
fields:identifier string Request that only some attributes are returned "type,identifier"
fields:player string Request that only some attributes are returned "updatedAt,name"
fields:playerFlag string Request that only some attributes are returned "updatedAt,name"
fields:server string Request that only some attributes are returned "name,ip,port"
filter:after date-time Only search players that were last seen after this time "2015-01-01T12:00:00Z"
filter:before date-time Only search players that were last seen before this time "2015-01-01T12:00:00Z"
filter:firstSeen string Filter players by when they were first seen.
pattern: ^((\d{4})(-(\d{2}))??(-(\d{2}))??(T(\d{2}):(\d{2})(:(\d{2}))??(\.(\d+))??(([\+\-]{1}\d{2}:\d{2})&#124;Z)??)??)?:((\d{4})(-(\d{2}))??(-(\d{2}))??(T(\d{2}):(\d{2})(:(\d{2}))??(\.(\d+))??(([\+\-]{1}\d{2}:\d{2})&#124;Z)??)??)?$
"2017-12-10T00:00:00Z:2017-12-11T00:00:00Z"
filter:identifiers string Comma separated list of identifier types to return. You must also specify identifiers under include. "name,BEGUID"
filter:lastSeen string Filter players by when they were last seen.
pattern: ^((\d{4})(-(\d{2}))??(-(\d{2}))??(T(\d{2}):(\d{2})(:(\d{2}))??(\.(\d+))??(([\+\-]{1}\d{2}:\d{2})&#124;Z)??)??)?:((\d{4})(-(\d{2}))??(-(\d{2}))??(T(\d{2}):(\d{2})(:(\d{2}))??(\.(\d+))??(([\+\-]{1}\d{2}:\d{2})&#124;Z)??)??)?$
"2017-12-10T00:00:00Z:2017-12-11T00:00:00Z"
filter:online boolean Filter players by online status. true
filter:organization string unique identifier of organization
pattern: \d+
"42"
filter:organizations string Comma separated list of organization IDs "42"
filter:playerFlags string Filter by player flags. Comma separated list of playerFlag IDs "1282dcb0-dda1-11e9-9581-fb5d7824a893"
filter:public string If true (default) show public search results. If false it will only show results for players that have been on one of your servers.
default: "true"
one of:"true" or "false"
"true"
filter:search string Search term(s) "Sisko"
filter:server:countries array Filter by country code. The country should be an ISO 3166-1 alpha-2 code. ["US","CA"]
filter:server:game string Filter by game id "ark"
filter:server:maxDistance integer Max distance allowed in kilometers. 5000
filter:server:players:max integer Maximum number of players
default: "Infinity"
Range: 0 <= value
42
filter:server:players:min integer Minimum number of players
default: 0
Range: 0 <= value
42
filter:server:search string Search term(s) "PVE"
filter:server:status string Filter by server status
one of:"online" or "offline" or "dead" or "invalid"
"online"
filter:servers string Comma separated list of server IDs "42"
filter:sessions:at date-time Filter players by if they were online at a certain time. "2015-01-01T12:00:00Z"
include string Relations to include. Comma separated. Valid: server, identifier "identifiers"
page:key string Page key. The value to start from. The prev and next links provide this value automatically. It's recommended that you don't manually provide this value. "100"
page:offset integer Page offset. Offset is only used with filter[search].
Range: 0 <= value <= 90
"50"
page:rel string Direction. Next/prev records based on key.
one of:"next" or "prev"
"next"
page:size integer Number of players to return per page
default: 10
Range: 1 <= value <= 100
42
sort string Sorting options. Default will sort by relevance. createdAt, updatedAt, name, firstSeen, lastSeen
default: "-updatedAt"
"-createdAt"

Curl Example

$ curl -n https://api.battlemetrics.com/players
 -G \
  -d filter[servers]=42 \
  -d filter[organizations]=42 \
  -d filter[server][search]=PVE \
  -d filter[server][game]=ark \
  -d filter[server][status]=online \
  -d filter[server][countries][]=US \
  -d filter[server][countries][]=CA \
  -d filter[server][maxDistance]=5000 \
  -d filter[server][players][min]=42 \
  -d filter[server][players][max]=42 \
  -d filter[server][features][469a1706-c8be-11e7-9d7a-e3ed64915530]=true \
  -d filter[server][features][11bc8572-ca45-11e7-bad6-2f023a014d57][or][]=1a7c6614-ca45-11e7-84a2-8b4c8bd3712b \
  -d filter[server][features][11bc8572-ca45-11e7-bad6-2f023a014d57][or][]=1abb5fb8-ca45-11e7-858b-affed11cb7fd \
  -d filter[organization]=42 \
  -d filter[search]=Sisko \
  -d filter[before]=2015-01-01T12%3A00%3A00Z \
  -d filter[after]=2015-01-01T12%3A00%3A00Z \
  -d filter[firstSeen]=2017-12-10T00%3A00%3A00Z%3A2017-12-11T00%3A00%3A00Z \
  -d filter[lastSeen]=2017-12-10T00%3A00%3A00Z%3A2017-12-11T00%3A00%3A00Z \
  -d filter[online]=true \
  -d filter[public]=true \
  -d filter[identifiers]=name%2CBEGUID \
  -d filter[sessions][at]=2015-01-01T12%3A00%3A00Z \
  -d filter[playerFlags]=1282dcb0-dda1-11e9-9581-fb5d7824a893 \
  -d page[size]=42 \
  -d page[key]=100 \
  -d page[offset]=50 \
  -d page[rel]=next \
  -d include=identifiers \
  -d sort=-createdAt \
  -d fields[player]=updatedAt%2Cname \
  -d fields[server]=name%2Cip%2Cport \
  -d fields[identifier]=type%2Cidentifier \
  -d fields[playerFlag]=updatedAt%2Cname \
  -d fields[flagPlayer]=addedAt

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "type": "player",
      "id": "42",
      "attributes": {
        "id": "42",
        "createdAt": "2015-01-01T12:00:00Z",
        "updatedAt": "2015-01-01T12:00:00Z",
        "name": "Quark",
        "private": false,
        "positiveMatch": false
      },
      "meta": {
        "metadata": [

        ]
      },
      "relationships": {
        "organizations": {
          "data": [
            {
              "type": "organization",
              "id": "42"
            }
          ]
        },
        "server": {
          "data": {
            "type": "server",
            "id": "42"
          }
        },
        "servers": {
          "data": [
            {
              "type": "server",
              "id": "42",
              "meta": {
                "firstSeen": "2015-01-01T12:00:00Z",
                "lastSeen": "2015-01-01T12:00:00Z",
                "timePlayed": 42,
                "online": true
              }
            }
          ]
        },
        "user": {
          "data": {
            "type": "user",
            "id": "42"
          }
        }
      }
    }
  ],
  "included": [

  ],
  "links": {
    "next": "https://api.battlemetrics.com/players?page[size]=10&key=2016-10-05T14:35:51.962Z",
    "prev": "https://api.battlemetrics.com/players?page[size]=10&key=2015-10-05T14:35:51.962Z"
  }
}

Player info. When servers are included we add timePlayed, firstSeen, lastSeen, and online properties under meta.

GET /players/{player_id}

Optional Parameters

Name Type Description Example
fields:flagPlayer string Request that only some attributes are returned "addedAt"
fields:identifier string Request that only some attributes are returned "type,identifier"
fields:player string Request that only some attributes are returned "updatedAt,name"
fields:playerFlag string Request that only some attributes are returned "updatedAt,name"
fields:server string Request that only some attributes are returned "name,ip,port"
filter:identifiers string Comma separated list of identifier types to return. You must also specify identifiers under include. "name,BEGUID"
filter:servers string Comma separated list of server IDs "42"
include string Relations to include. Comma separated. Valid values: server, identifier, playerNote, playerCounter, playerFlag, flagPlayer "server,identifier"
relations:flagPlayer string Request that only some relationships are returned "a,b"
relations:identifier string Request that only some relationships are returned "a,b"
relations:player string Request that only some relationships are returned "a,b"
relations:playerFlag string Request that only some relationships are returned "a,b"
relations:server string Request that only some relationships are returned "a,b"

Curl Example

$ curl -n https://api.battlemetrics.com/players/$PLAYER_ID
 -G \
  -d include=server%2Cidentifier \
  -d fields[player]=updatedAt%2Cname \
  -d fields[server]=name%2Cip%2Cport \
  -d fields[identifier]=type%2Cidentifier \
  -d fields[playerFlag]=updatedAt%2Cname \
  -d fields[flagPlayer]=addedAt \
  -d relations[player]=a%2Cb \
  -d relations[server]=a%2Cb \
  -d relations[identifier]=a%2Cb \
  -d relations[playerFlag]=a%2Cb \
  -d relations[flagPlayer]=a%2Cb \
  -d filter[servers]=42 \
  -d filter[identifiers]=name%2CBEGUID

Response Example

HTTP/2.0 200 OK
{
  "data": {
    "type": "player",
    "id": "42",
    "attributes": {
      "id": "42",
      "createdAt": "2015-01-01T12:00:00Z",
      "updatedAt": "2015-01-01T12:00:00Z",
      "name": "Quark",
      "private": false,
      "positiveMatch": false
    },
    "meta": {
      "metadata": [

      ]
    },
    "relationships": {
      "organizations": {
        "data": [
          {
            "type": "organization",
            "id": "42"
          }
        ]
      },
      "server": {
        "data": {
          "type": "server",
          "id": "42"
        }
      },
      "servers": {
        "data": [
          {
            "type": "server",
            "id": "42",
            "meta": {
              "firstSeen": "2015-01-01T12:00:00Z",
              "lastSeen": "2015-01-01T12:00:00Z",
              "timePlayed": 42,
              "online": true
            }
          }
        ]
      },
      "user": {
        "data": {
          "type": "user",
          "id": "42"
        }
      }
    }
  },
  "included": [
    null
  ]
}

Returns the data we use for rendering time played history charts. Start and stop are truncated to the date.

GET /players/{player_id}/time-played-history/{server_id}

Required Parameters

Name Type Description Example
start date-time Start timestamp. Must be within three months of stop. "2015-01-01T12:00:00Z"
stop date-time Stop timestamp. Must be within three months of start. "2015-01-01T12:00:00Z"

Curl Example

$ curl -n https://api.battlemetrics.com/players/$PLAYER_ID/time-played-history/$SERVER_ID
 -G \
  -d start=2015-01-01T12%3A00%3A00Z \
  -d stop=2015-01-01T12%3A00%3A00Z

Response Example

HTTP/2.0 200 OK
{
  "meta": {
    "start": "2015-01-01T12:00:00Z",
    "stop": "2015-01-01T12:00:00Z"
  },
  "data": [
    {
      "type": "dataPoint",
      "attributes": {
        "timestamp": "2015-01-01T12:00:00Z",
        "group": 0,
        "name": "games.arma3.players",
        "max": 42,
        "value": 42,
        "min": 42
      }
    }
  ]
}

Returns server specifics for the given player and server.

GET /players/{player_id}/servers/{server_id}

Curl Example

$ curl -n https://api.battlemetrics.com/players/$PLAYER_ID/servers/$SERVER_ID

Response Example

HTTP/2.0 200 OK
{
  "data": {
    "type": "playerServerInformation",
    "attributes": {
      "firstSeen": "2015-01-01T12:00:00Z",
      "lastSeen": "2015-01-01T12:00:00Z",
      "timePlayed": 42,
      "online": true
    }
  }
}

Player Match Identifiers

Searches for one or more identifiers.

Consider the similar quick match endpoint unless you need the more advanced features of this endpoint. Quick match has some limitations on filtering and sorting. In exchange for fewer options you get faster results and a higher rate limit.

This API method is only available to authenticated users. It is also rate limited to five requests per second. Enterprise users have a higher rate limit of 15 requests per second.

The servers filter limits which servers you get when including server information and also limits results to players who have played on those servers.

Results will be returned sorted by the player's id by default.

POST /players/match

Required Parameters

Name Type Description Example
data/attributes:identifier string The Identifier "76561197960265720"
data/attributes:type string Identifier type
one of:"steamID" or "BEGUID" or "legacyBEGUID" or "ip" or "name" or "survivorName" or "steamFamilyShareOwner" or "conanCharName" or "egsID" or "eosID" or "funcomID" or "playFabID" or "mcUUID" or "7dtdEOS" or "battlebitHWID" or "hllWindowsID" or "palworldUID"
"steamID"
data/type string Resource type. Always "identifier"
one of:"identifier"
"identifier"

Curl Example

$ curl -n -X POST https://api.battlemetrics.com/players/match \
  -d '{
  "data": [
    {
      "type": "identifier",
      "attributes": {
        "type": "steamID",
        "identifier": "76561197960265720"
      }
    }
  ]
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "id": "example",
      "type": "identifier",
      "attributes": {
        "type": "steamID",
        "identifier": "76561197960265720",
        "lastSeen": "2015-01-01T12:00:00Z",
        "private": true,
        "metadata": null
      },
      "relationships": {
        "player": {
          "data": {
            "type": "player",
            "id": "42"
          }
        },
        "organizations": {
          "data": [
            {
              "type": "organization",
              "id": "42"
            }
          ]
        }
      }
    }
  ],
  "included": [

  ],
  "links": {
    "next": "https://api.battlemetrics.com/players/match?page[key]=2016-10-05T14:35:51.962Z&page[rel]=next",
    "prev": "https://api.battlemetrics.com/players/match?page[key]=2015-10-05T14:35:51.962Z&page[rel]=prev"
  }
}

Player Quick Match Identifiers

Searches for one or more identifiers.

This API method is only available to authenticated users. It is also rate limited to 10 requests per second. Enterprise users have a higher rate limit of 30 requests per second.

The servers filter limits which servers you get when including server information, it does not filter players by server.

Results will be returned sorted by the player's id.

POST /players/quick-match

Required Parameters

Name Type Description Example
data/attributes:identifier string The Identifier "76561197960265720"
data/attributes:type string Identifier type
one of:"steamID" or "BEGUID" or "legacyBEGUID" or "ip" or "name" or "survivorName" or "steamFamilyShareOwner" or "conanCharName" or "egsID" or "eosID" or "funcomID" or "playFabID" or "mcUUID" or "7dtdEOS" or "battlebitHWID" or "hllWindowsID" or "palworldUID"
"steamID"
data/type string Resource type. Always "identifier"
one of:"identifier"
"identifier"

Curl Example

$ curl -n -X POST https://api.battlemetrics.com/players/quick-match \
  -d '{
  "data": [
    {
      "type": "identifier",
      "attributes": {
        "type": "steamID",
        "identifier": "76561197960265720"
      }
    }
  ]
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "id": "example",
      "type": "identifier",
      "attributes": {
        "type": "steamID",
        "identifier": "76561197960265720",
        "lastSeen": "2015-01-01T12:00:00Z",
        "private": true,
        "metadata": null
      },
      "relationships": {
        "player": {
          "data": {
            "type": "player",
            "id": "42"
          }
        },
        "organizations": {
          "data": [
            {
              "type": "organization",
              "id": "42"
            }
          ]
        }
      }
    }
  ],
  "included": [

  ],
  "links": {
    "next": "https://api.battlemetrics.com/players/quick-match?page[key]=1,1&page[rel]=next",
    "prev": "https://api.battlemetrics.com/players/quick-match?page[key]=1,1&page[rel]=prev"
  }
}

Returns player's session history.

GET /players/{player_id}/relationships/sessions

Optional Parameters

Name Type Description Example
fields:identifier string Request that only some attributes are returned "type,identifier"
fields:server string Request that only some attributes are returned "name,ip,port"
fields:session string Request that only some attributes are returned "start,stop"
filter:organizations string Comma separated list of organization IDs "42"
filter:servers string Comma separated list of server IDs "42"
include string Relations to include. Comma separated. Valid: identifier, server "identifier"
page:key string Page key. The value to start from. The prev and next links provide this value automatically. It's recommended that you don't manually provide this value. "100"
page:rel string Direction. Next/prev records based on key.
one of:"next" or "prev"
"next"
page:size integer Number of players to return per page
default: 10
Range: 1 <= value <= 100
42

Curl Example

$ curl -n https://api.battlemetrics.com/players/$PLAYER_ID/relationships/sessions
 -G \
  -d filter[servers]=42 \
  -d filter[organizations]=42 \
  -d page[size]=42 \
  -d page[key]=100 \
  -d page[rel]=next \
  -d include=identifier \
  -d fields[session]=start%2Cstop \
  -d fields[identifier]=type%2Cidentifier \
  -d fields[server]=name%2Cip%2Cport

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "type": "session",
      "attributes": {
        "start": "2015-01-01T12:00:00Z",
        "stop": "2015-01-01T12:00:00Z",
        "firstTime": true,
        "name": "Quark",
        "private": false,
        "metadata": [

        ]
      },
      "relationships": {
        "server": {
          "data": {
            "type": "server",
            "id": "42"
          }
        },
        "organization": {
          "data": {
            "type": "organization",
            "id": "42"
          }
        },
        "player": {
          "data": {
            "type": "player",
            "id": "42"
          }
        },
        "identifiers": {
          "data": [
            {
              "type": "identifier",
              "id": "example"
            }
          ]
        }
      }
    }
  ],
  "included": [

  ],
  "links": {
    "next": "https://api.battlemetrics.com/players/1/relationshps/sessions?page[key]=2016-10-05T14:35:51.962Z&page[rel]=next",
    "prev": "https://api.battlemetrics.com/players/1/relationshps/sessions?page[key]=2015-10-05T14:35:51.962Z&page[rel]=prev"
  }
}

Player Counter

Stability: prototype

Player counter name and value from a trigger.

Attributes

Name Type Description Example
attributes:name string Counter Name "warnings"
attributes:value integer Counter value 2
id string unique identifier of playerCounter "42:42"
relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
relationships:player:data:id string unique identifier of player
pattern: \d+
"42"
relationships:player:data:type string Resource type. Always "player"
one of:"player"
"player"
type string Resource type. Always "playerCounter" "playerCounter"

Player Flag

Stability: prototype

Player Flag. Flags not associated with an organization will be considered personal and not visible to other organization users. Requires flag:read scope to view.

Attributes

Name Type Description Example
attributes:color string Flag color
pattern: ^#[0-9a-fA-F]{6}$
"example"
attributes:createdAt date-time When the flag was created "2015-01-01T12:00:00Z"
attributes:description nullable string Flag description null
attributes:icon nullable string Icon name
one of:null or "flag" or "alarm" or "attach_money" or "block" or "bookmark" or "check_circle_outline" or "emoji_objects" or "enhanced_encryption" or "error_outline" or "highlight_off" or "info" or "label" or "loyalty" or "monetization_on" or "note_add" or "notifications" or "notification_important" or "policy" or "verified_user" or "priority_high" or "remove_circle" or "report" or "star" or "thumb_down" or "thumb_up" or "visibility" or "warning" or "whatshot"
null
attributes:name string Flag name "example"
attributes:updatedAt date-time When the flag was last updated "2015-01-01T12:00:00Z"
id uuid unique identifier of player flag "01234567-89ab-cdef-0123-456789abcdef"
meta:shared boolean true
relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
relationships:user:data:id string unique identifier of user
pattern: \d+
"42"
relationships:user:data:type string Resource type. Always "user"
one of:"user"
"user"
type string Resource type. Always playerFlag.
one of:"playerFlag"
"playerFlag"

Player Flag Create

Create a new flag

POST /player-flags

Required Parameters

Name Type Description Example
data:attributes:color string Flag color
pattern: ^#[0-9a-fA-F]{6}$
"example"
data:attributes:description nullable string Flag description null
data:attributes:icon nullable string Icon name
one of:null or "flag" or "alarm" or "attach_money" or "block" or "bookmark" or "check_circle_outline" or "emoji_objects" or "enhanced_encryption" or "error_outline" or "highlight_off" or "info" or "label" or "loyalty" or "monetization_on" or "note_add" or "notifications" or "notification_important" or "policy" or "verified_user" or "priority_high" or "remove_circle" or "report" or "star" or "thumb_down" or "thumb_up" or "visibility" or "warning" or "whatshot"
null
data:attributes:name string Flag name "example"
data:type string Resource type. Always playerFlag.
one of:"playerFlag"
"playerFlag"

Optional Parameters

Name Type Description Example
data:relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
data:relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
data:relationships:user:data:id string unique identifier of user
pattern: \d+
"42"
data:relationships:user:data:type string Resource type. Always "user"
one of:"user"
"user"

Curl Example

$ curl -n -X POST https://api.battlemetrics.com/player-flags \
  -d '{
  "data": {
    "type": "playerFlag",
    "attributes": {
      "icon": null,
      "name": "example",
      "color": "example",
      "description": "example"
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      },
      "user": {
        "data": {
          "type": "user",
          "id": "42"
        }
      }
    }
  }
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 201 Created
{
  "data": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "type": "playerFlag",
    "meta": {
      "shared": true
    },
    "attributes": {
      "createdAt": "2015-01-01T12:00:00Z",
      "updatedAt": "2015-01-01T12:00:00Z",
      "icon": null,
      "name": "example",
      "color": "example",
      "description": "example"
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      },
      "user": {
        "data": {
          "type": "user",
          "id": "42"
        }
      }
    }
  }
}

Delete an existing flag.

DELETE /player-flags/{playerFlag_id}

Curl Example

$ curl -n -X DELETE https://api.battlemetrics.com/player-flags/$PLAYERFLAG_ID \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 204 No Content

Info for existing flag.

GET /player-flags/{playerFlag_id}

Curl Example

$ curl -n https://api.battlemetrics.com/player-flags/$PLAYERFLAG_ID

Response Example

HTTP/2.0 200 OK
{
  "data": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "type": "playerFlag",
    "meta": {
      "shared": true
    },
    "attributes": {
      "createdAt": "2015-01-01T12:00:00Z",
      "updatedAt": "2015-01-01T12:00:00Z",
      "icon": null,
      "name": "example",
      "color": "example",
      "description": "example"
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      },
      "user": {
        "data": {
          "type": "user",
          "id": "42"
        }
      }
    }
  }
}

List existing player flags.

GET /player-flags

Optional Parameters

Name Type Description Example
filter:personal boolean Hide/show personal flags true
include string Relations to include. Comma separated. Valid: organization "organization"
page:key string Page key. The value to start from. The prev and next links provide this value automatically. It's recommended that you don't manually provide this value. "100"
page:rel string Direction. Next/prev records based on key.
one of:"next" or "prev"
"next"
page:size integer Number of flags to return per page
default: 10
Range: 1 <= value <= 100
42

Curl Example

$ curl -n https://api.battlemetrics.com/player-flags
 -G \
  -d include=organization \
  -d filter[personal]=true \
  -d page[size]=42 \
  -d page[key]=100 \
  -d page[rel]=next

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "type": "playerFlag",
      "meta": {
        "shared": true
      },
      "attributes": {
        "createdAt": "2015-01-01T12:00:00Z",
        "updatedAt": "2015-01-01T12:00:00Z",
        "icon": null,
        "name": "example",
        "color": "example",
        "description": "example"
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organization",
            "id": "42"
          }
        },
        "user": {
          "data": {
            "type": "user",
            "id": "42"
          }
        }
      }
    }
  ],
  "included": [

  ],
  "links": {
    "next": "https://api.battlemetrics.com/player-flagss?page[size]=10&key=2016-10-05T14:35:51.962Z",
    "prev": "https://api.battlemetrics.com/player-flags?page[size]=10&key=2015-10-05T14:35:51.962Z"
  }
}

Update an existing flag.

PATCH /player-flags/{playerFlag_id}

Required Parameters

Name Type Description Example
data:attributes:color string Flag color
pattern: ^#[0-9a-fA-F]{6}$
"example"
data:attributes:description nullable string Flag description null
data:attributes:icon nullable string Icon name
one of:null or "flag" or "alarm" or "attach_money" or "block" or "bookmark" or "check_circle_outline" or "emoji_objects" or "enhanced_encryption" or "error_outline" or "highlight_off" or "info" or "label" or "loyalty" or "monetization_on" or "note_add" or "notifications" or "notification_important" or "policy" or "verified_user" or "priority_high" or "remove_circle" or "report" or "star" or "thumb_down" or "thumb_up" or "visibility" or "warning" or "whatshot"
null
data:attributes:name string Flag name "example"
data:id uuid unique identifier of player flag "01234567-89ab-cdef-0123-456789abcdef"
data:type string Resource type. Always playerFlag.
one of:"playerFlag"
"playerFlag"

Curl Example

$ curl -n -X PATCH https://api.battlemetrics.com/player-flags/$PLAYERFLAG_ID \
  -d '{
  "data": {
    "type": "playerFlag",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "attributes": {
      "icon": null,
      "name": "example",
      "color": "example",
      "description": "example"
    }
  }
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 200 OK
{
  "data": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "type": "playerFlag",
    "meta": {
      "shared": true
    },
    "attributes": {
      "createdAt": "2015-01-01T12:00:00Z",
      "updatedAt": "2015-01-01T12:00:00Z",
      "icon": null,
      "name": "example",
      "color": "example",
      "description": "example"
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      },
      "user": {
        "data": {
          "type": "user",
          "id": "42"
        }
      }
    }
  }
}

Player Note

Stability: prototype

Player Note. Notes must be associated with a player. If the note is not associated with an organization it will be personal/private. Requires note:read scope to view.

Attributes

Name Type Description Example
attributes:createdAt date-time when note was created "2015-01-01T12:00:00Z"
attributes:note string The note "example"
attributes:shared boolean If this note should be shared with friendly organizations. true
id string unique identifier of note
pattern: \d+
"example"
relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
relationships:player:data:id string unique identifier of player
pattern: \d+
"42"
relationships:player:data:type string Resource type. Always "player"
one of:"player"
"player"
relationships:user:data:id string unique identifier of user
pattern: \d+
"42"
relationships:user:data:type string Resource type. Always "user"
one of:"user"
"user"
type string Resource type. Always playerNote.
one of:"playerNote"
"playerNote"

Player Note Create

Create a new note

POST /players/{player_id}/relationships/notes

Required Parameters

Name Type Description Example
data:attributes:note string The note "example"
data:attributes:shared boolean If this note should be shared with friendly organizations. true
data:type string Resource type. Always playerNote.
one of:"playerNote"
"playerNote"

Optional Parameters

Name Type Description Example
data:relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
data:relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
data:relationships:player:data:id string unique identifier of player
pattern: \d+
"42"
data:relationships:player:data:type string Resource type. Always "player"
one of:"player"
"player"
data:relationships:trigger:data:id uuid Trigger ID "01234567-89ab-cdef-0123-456789abcdef"
data:relationships:trigger:data:type string Resource type. Always trigger.
one of:"trigger"
"trigger"
data:relationships:user:data:id string unique identifier of user
pattern: \d+
"42"
data:relationships:user:data:type string Resource type. Always "user"
one of:"user"
"user"

Curl Example

$ curl -n -X POST https://api.battlemetrics.com/players/$PLAYER_ID/relationships/notes \
  -d '{
  "data": {
    "type": "playerNote",
    "attributes": {
      "note": "example",
      "shared": true
    },
    "relationships": {
      "player": {
        "data": {
          "type": "player",
          "id": "42"
        }
      },
      "organization": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      },
      "user": {
        "data": {
          "type": "user",
          "id": "42"
        }
      },
      "trigger": {
        "data": {
          "type": "trigger",
          "id": "01234567-89ab-cdef-0123-456789abcdef"
        }
      }
    }
  }
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 201 Created
{
  "data": {
    "id": "example",
    "type": "playerNote",
    "attributes": {
      "note": "example",
      "shared": true,
      "createdAt": "2015-01-01T12:00:00Z"
    },
    "relationships": {
      "player": {
        "data": {
          "type": "player",
          "id": "42"
        }
      },
      "organization": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      },
      "user": {
        "data": {
          "type": "user",
          "id": "42"
        }
      },
      "trigger": {
        "data": {
          "type": "trigger",
          "id": "01234567-89ab-cdef-0123-456789abcdef"
        }
      }
    }
  }
}

Delete an existing note.

DELETE /players/{player_id}/relationships/notes/{playerNote_id}

Curl Example

$ curl -n -X DELETE https://api.battlemetrics.com/players/$PLAYER_ID/relationships/notes/$PLAYERNOTE_ID \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 204 No Content

Info for existing note.

GET /players/{player_id}/relationships/notes/{playerNote_id}

Curl Example

$ curl -n https://api.battlemetrics.com/players/$PLAYER_ID/relationships/notes/$PLAYERNOTE_ID

Response Example

HTTP/2.0 200 OK
{
  "data": {
    "id": "example",
    "type": "playerNote",
    "attributes": {
      "note": "example",
      "shared": true,
      "createdAt": "2015-01-01T12:00:00Z"
    },
    "relationships": {
      "player": {
        "data": {
          "type": "player",
          "id": "42"
        }
      },
      "organization": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      },
      "user": {
        "data": {
          "type": "user",
          "id": "42"
        }
      },
      "trigger": {
        "data": {
          "type": "trigger",
          "id": "01234567-89ab-cdef-0123-456789abcdef"
        }
      }
    }
  },
  "included": [

  ]
}

List existing note.

GET /players/{player_id}/relationships/notes

Optional Parameters

Name Type Description Example
filter:personal boolean Hide/show personal notes true
include string Relations to include. Comma separated. Valid: user,organization "user"
page:key string Page key. The value to start from. The prev and next links provide this value automatically. It's recommended that you don't manually provide this value. "100"
page:rel string Direction. Next/prev records based on key.
one of:"next" or "prev"
"next"
page:size integer Number of players to return per page
default: 10
Range: 1 <= value <= 100
42

Curl Example

$ curl -n https://api.battlemetrics.com/players/$PLAYER_ID/relationships/notes
 -G \
  -d include=user \
  -d filter[personal]=true \
  -d page[size]=42 \
  -d page[key]=100 \
  -d page[rel]=next

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "id": "example",
      "type": "playerNote",
      "attributes": {
        "note": "example",
        "shared": true,
        "createdAt": "2015-01-01T12:00:00Z"
      },
      "relationships": {
        "player": {
          "data": {
            "type": "player",
            "id": "42"
          }
        },
        "organization": {
          "data": {
            "type": "organization",
            "id": "42"
          }
        },
        "user": {
          "data": {
            "type": "user",
            "id": "42"
          }
        },
        "trigger": {
          "data": {
            "type": "trigger",
            "id": "01234567-89ab-cdef-0123-456789abcdef"
          }
        }
      }
    }
  ],
  "included": [

  ],
  "links": {
    "next": "https://api.battlemetrics.com/players?page[size]=10&key=2016-10-05T14:35:51.962Z",
    "prev": "https://api.battlemetrics.com/players?page[size]=10&key=2015-10-05T14:35:51.962Z"
  }
}

Update an existing note.

PATCH /players/{player_id}/relationships/notes/{playerNote_id}

Required Parameters

Name Type Description Example
data:attributes:note string The note "example"
data:attributes:shared boolean If this note should be shared with friendly organizations. true
data:id string unique identifier of note
pattern: \d+
"example"
data:type string Resource type. Always playerNote.
one of:"playerNote"
"playerNote"

Curl Example

$ curl -n -X PATCH https://api.battlemetrics.com/players/$PLAYER_ID/relationships/notes/$PLAYERNOTE_ID \
  -d '{
  "data": {
    "type": "playerNote",
    "id": "example",
    "attributes": {
      "note": "example",
      "shared": true
    }
  }
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 200 OK
{
  "data": {
    "id": "example",
    "type": "playerNote",
    "attributes": {
      "note": "example",
      "shared": true,
      "createdAt": "2015-01-01T12:00:00Z"
    },
    "relationships": {
      "player": {
        "data": {
          "type": "player",
          "id": "42"
        }
      },
      "organization": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      },
      "user": {
        "data": {
          "type": "user",
          "id": "42"
        }
      },
      "trigger": {
        "data": {
          "type": "trigger",
          "id": "01234567-89ab-cdef-0123-456789abcdef"
        }
      }
    }
  }
}

Player Stats

Stability: prototype

Includes information about the number of players seen during the requested time frame(s).

Attributes

Name Type Description Example
attributes:firstTimeSessionDuration number The average duration of first time player sessions in seconds. 42.0
attributes:maxPlayers number The maximum number of players online 42.0
attributes:minPlayers number The minimum number of players online 42.0
attributes:sessionDuration number The average duration of player sessions in seconds. 42.0
attributes:uniquePlayers number The number of unique player ids 42.0
attributes:uniquePlayersByCountry:unknown number 42.0
relationships:game:data:id string unique identifier of game
pattern: [a-z0-9]+
"ark"
relationships:game:data:type string Resource type. Always "game"
one of:"game"
"game"
relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
relationships:server:data:id string unique identifier of server
pattern: \d+
"42"
relationships:server:data:type string Resource type. Always "server"
one of:"server"
"server"
type string Resource type. Always "playerStats"
one of:"playerStats"
"playerStats"

Related Player Identifier

Stability: prototype

Provides information to find other players that have the same identifier. This is an extension of the identifier type with additional relations. Identifiers that are shared with more than 20 players will not return results and will have an additional meta property "commonIdentifier" that is set to true.

Attributes

Name Type Description Example
attributes:identifier string The Identifier "76561197960265720"
attributes:lastSeen date-time The last time we saw the identifier. "2015-01-01T12:00:00Z"
attributes:metadata nullable object Extra information about the identifier. The information available will vary. null
attributes:private boolean If the identifier should be considered private. true
attributes:type string Identifier type
one of:"steamID" or "BEGUID" or "legacyBEGUID" or "ip" or "name" or "survivorName" or "steamFamilyShareOwner" or "conanCharName" or "egsID" or "eosID" or "funcomID" or "playFabID" or "mcUUID" or "7dtdEOS" or "battlebitHWID" or "hllWindowsID" or "palworldUID"
"steamID"
id string Identifier ID
pattern: \d+
"example"
meta:commonIdentifier boolean true
relationships:organizations:data/id string unique identifier of organization
pattern: \d+
"42"
relationships:organizations:data/type string Resource type. Always "organization"
one of:"organization"
"organization"
relationships:player:data:id string unique identifier of player
pattern: \d+
"42"
relationships:player:data:type string Resource type. Always "player"
one of:"player"
"player"
relationships:relatedIdentifiers:data/id string Identifier ID
pattern: \d+
"example"
relationships:relatedIdentifiers:data/type string Resource type. Always "identifier"
one of:"identifier"
"identifier"
relationships:relatedPlayers:data/id string unique identifier of player
pattern: \d+
"42"
relationships:relatedPlayers:data/type string Resource type. Always "player"
one of:"player"
"player"
type string Resource type. Always "relatedIdentifier"
one of:"relatedIdentifier"
"relatedIdentifier"

Get player identifiers and related players and identifiers.

GET /players/{player_id}/relationships/related-identifiers

Optional Parameters

Name Type Description Example
fields:flagPlayer string Request that only some attributes are returned "addedAt"
fields:identifier string Request that only some attributes are returned "type,identifier"
fields:player string Request that only some attributes are returned "updatedAt,name"
fields:playerFlag string Request that only some attributes are returned "updatedAt,name"
filter:identifiers string Comma separated list of types to filter included identifiers by. "name,BEGUID"
filter:matchIdentifiers string Comma separated list of identifier types to match. "name,BEGUID"
include string Relations to include. Comma separated. Valid values: player, identifier, playerFlag, flagPlayer "player,identifier"
page:key string Page key. The value to start from. The prev and next links provide this value automatically. It's recommended that you don't manually provide this value. "100"
page:rel string Direction. Next/prev records based on key.
one of:"next" or "prev"
"next"
page:size integer Number of items to return per page
default: 100
Range: 1 <= value <= 100
42
relations:flagPlayer string Request that only some relationships are returned "a,b"
relations:identifier string Request that only some relationships are returned "a,b"
relations:player string Request that only some relationships are returned "a,b"
relations:playerFlag string Request that only some relationships are returned "a,b"

Curl Example

$ curl -n https://api.battlemetrics.com/players/$PLAYER_ID/relationships/related-identifiers
 -G \
  -d include=player%2Cidentifier \
  -d fields[player]=updatedAt%2Cname \
  -d fields[identifier]=type%2Cidentifier \
  -d fields[playerFlag]=updatedAt%2Cname \
  -d fields[flagPlayer]=addedAt \
  -d relations[player]=a%2Cb \
  -d relations[identifier]=a%2Cb \
  -d relations[playerFlag]=a%2Cb \
  -d relations[flagPlayer]=a%2Cb \
  -d filter[matchIdentifiers]=name%2CBEGUID \
  -d filter[identifiers]=name%2CBEGUID \
  -d page[size]=42 \
  -d page[key]=100 \
  -d page[rel]=next

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "id": "example",
      "meta": {
        "commonIdentifier": true
      },
      "type": "relatedIdentifier",
      "attributes": {
        "type": "steamID",
        "identifier": "76561197960265720",
        "lastSeen": "2015-01-01T12:00:00Z",
        "private": true,
        "metadata": null
      },
      "relationships": {
        "player": {
          "data": {
            "type": "player",
            "id": "42"
          }
        },
        "relatedPlayers": {
          "data": [
            {
              "type": "player",
              "id": "42"
            }
          ]
        },
        "relatedIdentifiers": {
          "data": [
            {
              "type": "identifier",
              "id": "example"
            }
          ]
        },
        "organizations": {
          "data": [
            {
              "type": "organization",
              "id": "42"
            }
          ]
        }
      }
    }
  ],
  "included": [
    null
  ],
  "links": {
    "next": "example",
    "prev": "example"
  }
}

Reserved Slot

Stability: prototype

The BattleMetrics reserved slot system.

Attributes

Name Type Description Example
attributes:createdAt date-time Timestamp of when the reserved slot was added "2016-10-05T14:35:51.962Z"
attributes:expires nullable date-time When the slot should expire. If null the reserved slot will not expire. "2016-11-05T14:35:51.962Z"
attributes:identifiers array An array of identifiers to associated with the reserved slot. Can link known identifiers, or manually provided ones. [1000,{"type":"steamID","identifier":"1111111111111111","manual":true}]
id uuid Slot ID "01234567-89ab-cdef-0123-456789abcdef"
meta object Custom metadata. Key value strings. Can be used in billing systems to track transactions, packages, etc. If you provide the meta object the entire object will be replaced.
relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
relationships:player:data:id string unique identifier of player
pattern: \d+
"42"
relationships:player:data:type string Resource type. Always "player"
one of:"player"
"player"
relationships:servers:data nullable array null
relationships:servers:data/id string unique identifier of server
pattern: \d+
"42"
relationships:servers:data/type string Resource type. Always "server"
one of:"server"
"server"
relationships:user:data:id string unique identifier of user
pattern: \d+
"42"
relationships:user:data:type string Resource type. Always "user"
one of:"user"
"user"
type string Resource type. Always reservedSlot.
one of:"reservedSlot"
"reservedSlot"

Reserved Slot Create

Add a player to the reserved slot list. Requires the reserved-slot:create scope.

POST /reserved-slots

Required Parameters

Name Type Description Example
data:attributes:expires nullable date-time When the slot should expire. If null the reserved slot will not expire. "2016-11-05T14:35:51.962Z"
data:attributes:identifiers array An array of identifiers to associated with the reserved slot. Can link known identifiers, or manually provided ones. [1000,{"type":"steamID","identifier":"1111111111111111","manual":true}]
data:relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
data:relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
data:relationships:player:data:id string unique identifier of player
pattern: \d+
"42"
data:relationships:player:data:type string Resource type. Always "player"
one of:"player"
"player"
data:relationships:servers:data nullable array null
data:relationships:servers:data/id string unique identifier of server
pattern: \d+
"42"
data:relationships:servers:data/type string Resource type. Always "server"
one of:"server"
"server"
data:relationships:user:data:id string unique identifier of user
pattern: \d+
"42"
data:relationships:user:data:type string Resource type. Always "user"
one of:"user"
"user"
data:type string Resource type. Always reservedSlot.
one of:"reservedSlot"
"reservedSlot"

Optional Parameters

Name Type Description Example
data:meta object Custom metadata. Key value strings. Can be used in billing systems to track transactions, packages, etc. If you provide the meta object the entire object will be replaced.

Curl Example

$ curl -n -X POST https://api.battlemetrics.com/reserved-slots \
  -d '{
  "data": {
    "type": "reservedSlot",
    "meta": null,
    "attributes": {
      "expires": "2016-11-05T14:35:51.962Z",
      "identifiers": [
        1000,
        {
          "type": "steamID",
          "identifier": "1111111111111111",
          "manual": true
        }
      ]
    },
    "relationships": {
      "player": {
        "data": {
          "type": "player",
          "id": "42"
        }
      },
      "servers": {
        "data": [
          {
            "type": "server",
            "id": "42"
          }
        ]
      },
      "organization": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      },
      "user": {
        "data": {
          "type": "user",
          "id": "42"
        }
      }
    }
  }
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 201 Created
{
  "data": {
    "type": "reservedSlot",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "meta": null,
    "attributes": {
      "createdAt": "2016-10-05T14:35:51.962Z",
      "expires": "2016-11-05T14:35:51.962Z",
      "identifiers": [
        1000,
        {
          "type": "steamID",
          "identifier": "1111111111111111",
          "manual": true
        }
      ]
    },
    "relationships": {
      "player": {
        "data": {
          "type": "player",
          "id": "42"
        }
      },
      "servers": {
        "data": [
          {
            "type": "server",
            "id": "42"
          }
        ]
      },
      "organization": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      },
      "user": {
        "data": {
          "type": "user",
          "id": "42"
        }
      }
    }
  }
}

Delete an existing reserved slot. Requires the reserved-slot:delete scope.

DELETE /reserved-slots/{reservedSlot_id}

Curl Example

$ curl -n -X DELETE https://api.battlemetrics.com/reserved-slots/$RESERVEDSLOT_ID \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 204 No Content

Info for existing reservedSlot. Requires the reserved-slot:read scope.

GET /reserved-slots/{reservedSlot_id}

Optional Parameters

Name Type Description Example
fields:identifier string Request that only some attributes are returned "type,identifier"
fields:organization string Request that only some attributes are returned "tz,banTemplate"
fields:player string Request that only some attributes are returned "updatedAt,name"
fields:reservedSlot string Request that only some attributes are returned "expires"
fields:server string Request that only some attributes are returned "name,ip,port"
fields:user string Request that only some attributes are returned "nickname"
include string Relations to include. Comma separated. Valid values: organization, player, server, playerIdentifiers, user "player,server"

Curl Example

$ curl -n https://api.battlemetrics.com/reserved-slots/$RESERVEDSLOT_ID
 -G \
  -d include=player%2Cserver \
  -d fields[reservedSlot]=expires \
  -d fields[organization]=tz%2CbanTemplate \
  -d fields[player]=updatedAt%2Cname \
  -d fields[server]=name%2Cip%2Cport \
  -d fields[identifier]=type%2Cidentifier \
  -d fields[user]=nickname

Response Example

HTTP/2.0 200 OK
{
  "data": {
    "type": "reservedSlot",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "meta": null,
    "attributes": {
      "createdAt": "2016-10-05T14:35:51.962Z",
      "expires": "2016-11-05T14:35:51.962Z",
      "identifiers": [
        1000,
        {
          "type": "steamID",
          "identifier": "1111111111111111",
          "manual": true
        }
      ]
    },
    "relationships": {
      "player": {
        "data": {
          "type": "player",
          "id": "42"
        }
      },
      "servers": {
        "data": [
          {
            "type": "server",
            "id": "42"
          }
        ]
      },
      "organization": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      },
      "user": {
        "data": {
          "type": "user",
          "id": "42"
        }
      }
    }
  },
  "included": [
    null
  ]
}

List, search and filter existing reserved slots.

Requires the reserved-slot:read scope.

GET /reserved-slots

Optional Parameters

Name Type Description Example
fields:organization string Request that only some attributes are returned "tz,banTemplate"
fields:player string Request that only some attributes are returned "updatedAt,name"
fields:reservedSlot string Request that only some attributes are returned "expires"
fields:server string Request that only some attributes are returned "name,ip,port"
fields:user string Request that only some attributes are returned "nickname"
filter:expired string If true, show expired, otherwise hide expired reserved slots.
one of:"true" or "false"
"true"
filter:organization string unique identifier of organization
pattern: \d+
"42"
filter:player string unique identifier of player
pattern: \d+
"42"
filter:search string Search term(s) "Player Name"
filter:server string unique identifier of server
pattern: \d+
"42"
include string Relations to include. Comma separated. Valid: server, player, organization, user "server,player"
page:key string Page key. The value to start from. The prev and next links provide this value automatically. It's recommended that you don't manually provide this value. "100"
page:offset integer Offset pagination is only used with filter[search]
Range: 0 <= value <= 100
42
page:rel string Direction. Next/prev records based on key.
one of:"next" or "prev"
"next"
page:size integer Number of reserved slots to return per page
default: 10
Range: 1 <= value <= 100
42
sort string Sorting options. createdAt, expires
default: "-createdAt"
"-createdAt"

Curl Example

$ curl -n https://api.battlemetrics.com/reserved-slots
 -G \
  -d filter[expired]=true \
  -d filter[server]=42 \
  -d filter[organization]=42 \
  -d filter[player]=42 \
  -d filter[search]=Player+Name \
  -d page[size]=42 \
  -d page[offset]=42 \
  -d page[key]=100 \
  -d page[rel]=next \
  -d include=server%2Cplayer \
  -d sort=-createdAt \
  -d fields[reservedSlot]=expires \
  -d fields[organization]=tz%2CbanTemplate \
  -d fields[player]=updatedAt%2Cname \
  -d fields[server]=name%2Cip%2Cport \
  -d fields[user]=nickname

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "type": "reservedSlot",
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "meta": null,
      "attributes": {
        "createdAt": "2016-10-05T14:35:51.962Z",
        "expires": "2016-11-05T14:35:51.962Z",
        "identifiers": [
          1000,
          {
            "type": "steamID",
            "identifier": "1111111111111111",
            "manual": true
          }
        ]
      },
      "relationships": {
        "player": {
          "data": {
            "type": "player",
            "id": "42"
          }
        },
        "servers": {
          "data": [
            {
              "type": "server",
              "id": "42"
            }
          ]
        },
        "organization": {
          "data": {
            "type": "organization",
            "id": "42"
          }
        },
        "user": {
          "data": {
            "type": "user",
            "id": "42"
          }
        }
      }
    }
  ],
  "included": [

  ],
  "links": {
    "next": "https://api.battlemetrics.com/reserved-slots?page[size]=10&key=2016-10-05T14:35:51.962Z",
    "prev": "https://api.battlemetrics.com/reserved-slots?page[size]=10&key=2015-10-05T14:35:51.962Z"
  }
}

Update an existing reserved slot. Requires the reserved-slot:update scope.

PATCH /reserved-slots/{reservedSlot_id}

Required Parameters

Name Type Description Example
data:id uuid Slot ID "01234567-89ab-cdef-0123-456789abcdef"
data:type string Resource type. Always reservedSlot.
one of:"reservedSlot"
"reservedSlot"

Optional Parameters

Name Type Description Example
data:attributes:expires nullable date-time When the slot should expire. If null the reserved slot will not expire. "2016-11-05T14:35:51.962Z"
data:attributes:identifiers array An array of identifiers to associated with the reserved slot. Can link known identifiers, or manually provided ones. [1000,{"type":"steamID","identifier":"1111111111111111","manual":true}]
data:meta object Custom metadata. Key value strings. Can be used in billing systems to track transactions, packages, etc. If you provide the meta object the entire object will be replaced.
data:relationships:servers:data nullable array null
data:relationships:servers:data/id string unique identifier of server
pattern: \d+
"42"
data:relationships:servers:data/type string Resource type. Always "server"
one of:"server"
"server"

Curl Example

$ curl -n -X PATCH https://api.battlemetrics.com/reserved-slots/$RESERVEDSLOT_ID \
  -d '{
  "data": {
    "type": "reservedSlot",
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "meta": null,
    "attributes": {
      "expires": "2016-11-05T14:35:51.962Z",
      "identifiers": [
        1000,
        {
          "type": "steamID",
          "identifier": "1111111111111111",
          "manual": true
        }
      ]
    },
    "relationships": {
      "servers": {
        "data": [
          {
            "type": "server",
            "id": "42"
          }
        ]
      }
    }
  }
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 200 OK
{
  "type": "reservedSlot",
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "meta": null,
  "attributes": {
    "createdAt": "2016-10-05T14:35:51.962Z",
    "expires": "2016-11-05T14:35:51.962Z",
    "identifiers": [
      1000,
      {
        "type": "steamID",
        "identifier": "1111111111111111",
        "manual": true
      }
    ]
  },
  "relationships": {
    "player": {
      "data": {
        "type": "player",
        "id": "42"
      }
    },
    "servers": {
      "data": [
        {
          "type": "server",
          "id": "42"
        }
      ]
    },
    "organization": {
      "data": {
        "type": "organization",
        "id": "42"
      }
    },
    "user": {
      "data": {
        "type": "user",
        "id": "42"
      }
    }
  }
}

Server

Stability: prototype

Servers

Attributes

Name Type Description Example
attributes:address nullable string IP "play.example.com"
attributes:country string The country the server is located in
Length: 2
"US"
attributes:createdAt date-time When the server was added to the system "2015-01-01T12:00:00Z"
attributes:details object Game and server specific information. Will vary from server to server. You should provide reasonable defaults, nothing is guaranteed.
attributes:id string unique identifier of server
pattern: \d+
"42"
attributes:ip string IP "127.0.0.1"
attributes:location array The server's longitude and latitude [47.6140999,-122.1966574]
attributes:maxPlayers integer The max number of players allowed on the server 42
attributes:metadata:betaSourceProtocol boolean Use new implementation of Source protocol. true
attributes:metadata:clientPerf boolean If client perf is enabled. true
attributes:metadata:connectionType string Connection type for Rust servers.
one of:"source" or "ws"
"source"
attributes:metadata:disableLocked nullable boolean If set to true RCON connection can not be enabled by the user. null
attributes:metadata:disabledReason nullable string Reason why the RCON connection is disabled. null
attributes:metadata:hasSourceMod nullable boolean If we have detected sourcemod. null
attributes:metadata:hllGetPlayerInfo boolean HLL. Control use of playerinfo command.
default: true
true
attributes:metadata:hllPlayerListInterval integer HLL. How often we should run get playerids and playerinfo commands.
default: 90
Range: 60 <= value <= 300
42
attributes:metadata:logSecret nullable string Log secret for Source games null
attributes:metadata:rconIP string Use a different IP for RCON connections "example"
attributes:metadata:reservedSlotKickReason string Kick message for the reserved slot system. "example"
attributes:metadata:reservedSlots integer The number of reserved slots for this server.
Range: 0 <= value
42
attributes:metadata:reservedSlotsKickLastToJoin boolean If the last player to join should be kicked when a player on the reserved slot list joins. true
attributes:metadata:statusInterval integer Rust. How often we should request server status via RCON.
Range: 15 <= value <= 300
42
attributes:metadata:useConnectionPool boolean HLL. Use a connection pool to increase command responsiveness. true
attributes:metadata:useGetChat boolean Ark & DNL. If we should use getchat, or getgamelog command. true
attributes:metadata:username string RCON username for RS2: Vietnam. "example"
attributes:name string Server name "Server Name"
attributes:players integer The number of players currently on the server 42
attributes:port integer The server's game port
Range: 0 <= value <= 65535
2302
attributes:portQuery integer The server's query port
Range: 0 <= value <= 65535
2303
attributes:private boolean Private servers are only visible to users with RCON access to the server. false
attributes:queryStatus nullable string Current query status
one of:null or "valid" or "invalid" or "timeout"
null
attributes:rank nullable integer The server's rank. If the server's rank is null then it has been de-ranked. null
attributes:rconActive nullable boolean Only available when authenticated. True when the RCON connection is enabled. This does not mean we are connected, only that we will connect if able. null
attributes:rconDisconnected nullable date-time When we last lost connection. Must be authenticated and have RCON access to the server. null
attributes:rconLastConnected nullable date-time The last time we were able to connect. Must be authenticated and have RCON access to the server. null
attributes:rconStatus nullable string Current rcon status. Must be authenticated and have RCON access to the server.
one of:null or "connected" or "disconnected" or "password-rejected" or "timeout" or "refused" or "unknown"
null
attributes:status string Server status. Available server information will be limited when status is "removed"
one of:"online" or "offline" or "dead" or "removed" or "invalid"
"online"
attributes:updatedAt date-time When the server was last updated "2015-01-01T12:00:00Z"
id string unique identifier of server
pattern: \d+
"42"
relationships:defaultBanList:data:id uuid Ban ID "01234567-89ab-cdef-0123-456789abcdef"
relationships:defaultBanList:data:type string Resource type. Always banList.
one of:"banList"
"banList"
relationships:game:data:id string unique identifier of game
pattern: [a-z0-9]+
"ark"
relationships:game:data:type string Resource type. Always "game"
one of:"game"
"game"
relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
relationships:serverGroup:data:id uuid unique identifier of server group "01234567-89ab-cdef-0123-456789abcdef"
relationships:serverGroup:data:type string Resource type. Always "serverGroup"
one of:"serverGroup"
"serverGroup"
relationships:serverGroup:meta:leader boolean true
type string Resource type. Always "server"
one of:"server"
"server"

List, search and filter servers.

You may filter by game features with one of the following formats:

Select Type Feature: ?filter[features][featureId][]=optionId

Boolean Type Feature: ?filter[features][featureId]=true

Range Type Feature:
Ranges are inclusive.
50 or less: ?filter[features][featureId]=:50
50 or more: ?filter[features][featureId]=50:
50 to 100: ?filter[features][featureId]=50:100

GET /servers

Optional Parameters

Name Type Description Example
fields:server string Request that only some attributes are returned "name,ip,port"
filter:favorites boolean Filter to servers that you have favorited. true
filter:game string Filter by game id "ark"
filter:groupLeader boolean True to only return group leaders, false to exclude them. true
filter:groups string Return servers that belong to a group "example"
filter:ids:blacklist string Don't include servers with the given id(s). Comma separated. 123
filter:ids:whitelist string Only include servers with the given id(s). Comma separated. 123
filter:maxDistance integer Max distance allowed in kilometers. 5000
filter:organizations string Filter servers by organization id(s). Comma separated. 123
filter:players:max integer Maximum number of players
default: "Infinity"
Range: 0 <= value
42
filter:players:min integer Minimum number of players
default: 0
Range: 0 <= value
42
filter:rcon boolean Filter servers that you have RCON access to. true
filter:search string Search term(s) "PVE"
filter:status string Filter by server status "online"
include string Relations to include. Comma separated. Valid values: serverGroup "serverGroup"
location string Your location. Only useful when sorting by distance. Format is: longitude,latitude
default: "Location based on IP"
"47.6140999,-122.1966574"
page:key string Page key. The value to start from. The prev and next links provide this value automatically. It's recommended that you don't manually provide this value. "100"
page:offset integer Page offset. Offset is used with filter[search] and sort=distance.
Range: 0 <= value <= 90
"50"
page:rel string Direction. Next/prev records based on key.
one of:"next" or "prev"
"next"
page:size integer Number of players to return per page
default: 10
Range: 1 <= value <= 100
42
relations:server string Request that only some relationships are returned "a,b"
sort string Sorting options. Default will sort by relevance when searching. Valid options: rank, name, players, distance
default: "rank"
"example"

Curl Example

$ curl -n https://api.battlemetrics.com/servers
 -G \
  -d location=47.6140999%2C-122.1966574 \
  -d include=serverGroup \
  -d filter[search]=PVE \
  -d filter[game]=ark \
  -d filter[status]=online \
  -d filter[countries][]=US \
  -d filter[countries][]=CA \
  -d filter[maxDistance]=5000 \
  -d filter[players][min]=42 \
  -d filter[players][max]=42 \
  -d filter[features][469a1706-c8be-11e7-9d7a-e3ed64915530]=true \
  -d filter[features][11bc8572-ca45-11e7-bad6-2f023a014d57][or][]=1a7c6614-ca45-11e7-84a2-8b4c8bd3712b \
  -d filter[features][11bc8572-ca45-11e7-bad6-2f023a014d57][or][]=1abb5fb8-ca45-11e7-858b-affed11cb7fd \
  -d filter[rcon]=true \
  -d filter[favorites]=true \
  -d filter[groups]=example \
  -d filter[groupLeader]=true \
  -d filter[ids][whitelist]=123 \
  -d filter[ids][blacklist]=123 \
  -d filter[organizations]=123 \
  -d page[size]=42 \
  -d page[key]=100 \
  -d page[offset]=50 \
  -d page[rel]=next \
  -d sort=example \
  -d fields[server]=name%2Cip%2Cport \
  -d relations[server]=a%2Cb

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "type": "server",
      "id": "42",
      "attributes": {
        "id": "42",
        "name": "Server Name",
        "address": "play.example.com",
        "ip": "127.0.0.1",
        "port": 2302,
        "portQuery": 2303,
        "players": 42,
        "maxPlayers": 42,
        "rank": 42,
        "createdAt": "2015-01-01T12:00:00Z",
        "updatedAt": "2015-01-01T12:00:00Z",
        "location": [
          47.6140999,
          -122.1966574
        ],
        "country": "US",
        "status": "online",
        "details": null,
        "metadata": {
        },
        "rconActive": true,
        "queryStatus": null,
        "rconStatus": null,
        "rconLastConnected": "2015-01-01T12:00:00Z",
        "rconDisconnected": "2015-01-01T12:00:00Z",
        "private": false
      },
      "relationships": {
        "game": {
          "data": {
            "type": "game",
            "id": "ark"
          }
        }
      }
    }
  ],
  "included": [
    null
  ],
  "links": {
    "next": "https://api.battlemetrics.com/servers?page[size]=10&key=2016-10-05T14:35:51.962Z",
    "prev": "https://api.battlemetrics.com/servers?page[size]=10&key=2015-10-05T14:35:51.962Z"
  }
}

Server Create

Add a server to the system.

POST /servers

Required Parameters

Name Type Description Example
data:attributes:ip string IP "127.0.0.1"
data:attributes:metadata:betaSourceProtocol boolean Use new implementation of Source protocol. true
data:attributes:metadata:clientPerf boolean If client perf is enabled. true
data:attributes:metadata:connectionType string Connection type for Rust servers.
one of:"source" or "ws"
"source"
data:attributes:metadata:disableLocked nullable boolean If set to true RCON connection can not be enabled by the user. null
data:attributes:metadata:disabledReason nullable string Reason why the RCON connection is disabled. null
data:attributes:metadata:hasSourceMod nullable boolean If we have detected sourcemod. null
data:attributes:metadata:hllGetPlayerInfo boolean HLL. Control use of playerinfo command.
default: true
true
data:attributes:metadata:hllPlayerListInterval integer HLL. How often we should run get playerids and playerinfo commands.
default: 90
Range: 60 <= value <= 300
42
data:attributes:metadata:logSecret nullable string Log secret for Source games null
data:attributes:metadata:rconIP string Use a different IP for RCON connections "example"
data:attributes:metadata:reservedSlotKickReason string Kick message for the reserved slot system. "example"
data:attributes:metadata:reservedSlots integer The number of reserved slots for this server.
Range: 0 <= value
42
data:attributes:metadata:reservedSlotsKickLastToJoin boolean If the last player to join should be kicked when a player on the reserved slot list joins. true
data:attributes:metadata:statusInterval integer Rust. How often we should request server status via RCON.
Range: 15 <= value <= 300
42
data:attributes:metadata:useConnectionPool boolean HLL. Use a connection pool to increase command responsiveness. true
data:attributes:metadata:useGetChat boolean Ark & DNL. If we should use getchat, or getgamelog command. true
data:attributes:metadata:username string RCON username for RS2: Vietnam. "example"
data:attributes:port integer The server's game port
Range: 0 <= value <= 65535
2302
data:attributes:portQuery integer The server's query port
Range: 0 <= value <= 65535
2303
data:attributes:portRCON integer Port to use for RCON connections. It is not possible to retrieve the RCON port. This is only used for updates.
Range: 10 <= value <= 65535
2302
data:attributes:rconPassword string Password to use for RCON connections. It is not possible to retrieve the password. This is only used for updates.
Length: 1..∞
"password"
data:relationships:defaultBanList:data:id uuid Ban ID "01234567-89ab-cdef-0123-456789abcdef"
data:relationships:defaultBanList:data:type string Resource type. Always banList.
one of:"banList"
"banList"
data:relationships:game:data:id string unique identifier of game
pattern: [a-z0-9]+
"ark"
data:relationships:game:data:type string Resource type. Always "game"
one of:"game"
"game"
data:relationships:gsp:data:id string unique identifier of gsp "station9"
data:relationships:gsp:data:type string Resource type. Always "gsp"
one of:"gsp"
"gsp"
data:relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
data:relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
data:relationships:serverGroup:data:id uuid unique identifier of server group "01234567-89ab-cdef-0123-456789abcdef"
data:relationships:serverGroup:data:type string Resource type. Always "serverGroup"
one of:"serverGroup"
"serverGroup"
data:relationships:serverGroup:meta:leader boolean true
data:type string Resource type. Always "server"
one of:"server"
"server"

Curl Example

$ curl -n -X POST https://api.battlemetrics.com/servers \
  -d '{
  "data": {
    "type": "server",
    "attributes": {
      "ip": "127.0.0.1",
      "port": 2302,
      "portQuery": 2303,
      "portRCON": 2302,
      "rconPassword": "password",
      "metadata": {
      }
    },
    "relationships": {
      "game": {
        "data": {
          "type": "game",
          "id": "ark"
        }
      }
    }
  }
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 201 Created
{
  "data": {
    "type": "server",
    "id": "42",
    "attributes": {
      "id": "42",
      "name": "Server Name",
      "address": "play.example.com",
      "ip": "127.0.0.1",
      "port": 2302,
      "portQuery": 2303,
      "players": 42,
      "maxPlayers": 42,
      "rank": 42,
      "createdAt": "2015-01-01T12:00:00Z",
      "updatedAt": "2015-01-01T12:00:00Z",
      "location": [
        47.6140999,
        -122.1966574
      ],
      "country": "US",
      "status": "online",
      "details": null,
      "metadata": {
      },
      "rconActive": true,
      "queryStatus": null,
      "rconStatus": null,
      "rconLastConnected": "2015-01-01T12:00:00Z",
      "rconDisconnected": "2015-01-01T12:00:00Z",
      "private": false
    },
    "relationships": {
      "game": {
        "data": {
          "type": "game",
          "id": "ark"
        }
      }
    }
  }
}

To change the server IPs you must provide the following: ip/address, port and portQuery.

To change the server's RCON port, or RCON password you must provide both portRCON and rconPassword.

To change the server's metadata you must provide portRCON, rconPassword, and metadata.

You may change the server's address and RCON port, password, and metadata at the same time.

The ability to change a server to private is limited to enterprise users.

PATCH /servers/{server_id}

Required Parameters

Name Type Description Example
data:attributes:address nullable string IP "play.example.com"
data:attributes:ip string IP "127.0.0.1"
data:attributes:metadata:betaSourceProtocol boolean Use new implementation of Source protocol. true
data:attributes:metadata:clientPerf boolean If client perf is enabled. true
data:attributes:metadata:connectionType string Connection type for Rust servers.
one of:"source" or "ws"
"source"
data:attributes:metadata:disableLocked nullable boolean If set to true RCON connection can not be enabled by the user. null
data:attributes:metadata:disabledReason nullable string Reason why the RCON connection is disabled. null
data:attributes:metadata:hasSourceMod nullable boolean If we have detected sourcemod. null
data:attributes:metadata:hllGetPlayerInfo boolean HLL. Control use of playerinfo command.
default: true
true
data:attributes:metadata:hllPlayerListInterval integer HLL. How often we should run get playerids and playerinfo commands.
default: 90
Range: 60 <= value <= 300
42
data:attributes:metadata:logSecret nullable string Log secret for Source games null
data:attributes:metadata:rconIP string Use a different IP for RCON connections "example"
data:attributes:metadata:reservedSlotKickReason string Kick message for the reserved slot system. "example"
data:attributes:metadata:reservedSlots integer The number of reserved slots for this server.
Range: 0 <= value
42
data:attributes:metadata:reservedSlotsKickLastToJoin boolean If the last player to join should be kicked when a player on the reserved slot list joins. true
data:attributes:metadata:statusInterval integer Rust. How often we should request server status via RCON.
Range: 15 <= value <= 300
42
data:attributes:metadata:useConnectionPool boolean HLL. Use a connection pool to increase command responsiveness. true
data:attributes:metadata:useGetChat boolean Ark & DNL. If we should use getchat, or getgamelog command. true
data:attributes:metadata:username string RCON username for RS2: Vietnam. "example"
data:attributes:port integer The server's game port
Range: 0 <= value <= 65535
2302
data:attributes:portQuery integer The server's query port
Range: 0 <= value <= 65535
2303
data:attributes:portRCON integer Port to use for RCON connections. It is not possible to retrieve the RCON port. This is only used for updates.
Range: 10 <= value <= 65535
2302
data:attributes:private boolean Private servers are only visible to users with RCON access to the server. false
data:attributes:rconPassword string Password to use for RCON connections. It is not possible to retrieve the password. This is only used for updates.
Length: 1..∞
"password"
data:id string unique identifier of server
pattern: \d+
"42"
data:relationships:defaultBanList:data string
data:type string Resource type. Always "server"
one of:"server"
"server"

Curl Example

$ curl -n -X PATCH https://api.battlemetrics.com/servers/$SERVER_ID \
  -d '{
  "data": {
    "type": "server",
    "id": "42",
    "attributes": {
      "portRCON": 2302,
      "rconPassword": "password",
      "metadata": {
      },
      "ip": "127.0.0.1",
      "address": "play.example.com",
      "port": 2302,
      "portQuery": 2303,
      "private": false
    },
    "relationships": {
      "defaultBanList": {
        "data": {
          "type": "banList",
          "id": "01234567-89ab-cdef-0123-456789abcdef"
        }
      }
    }
  }
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 200 OK
{
  "data": {
    "type": "server",
    "id": "42",
    "attributes": {
      "id": "42",
      "name": "Server Name",
      "address": "play.example.com",
      "ip": "127.0.0.1",
      "port": 2302,
      "portQuery": 2303,
      "players": 42,
      "maxPlayers": 42,
      "rank": 42,
      "createdAt": "2015-01-01T12:00:00Z",
      "updatedAt": "2015-01-01T12:00:00Z",
      "location": [
        47.6140999,
        -122.1966574
      ],
      "country": "US",
      "status": "online",
      "details": null,
      "metadata": {
      },
      "rconActive": true,
      "queryStatus": null,
      "rconStatus": null,
      "rconLastConnected": "2015-01-01T12:00:00Z",
      "rconDisconnected": "2015-01-01T12:00:00Z",
      "private": false
    },
    "relationships": {
      "game": {
        "data": {
          "type": "game",
          "id": "ark"
        }
      }
    }
  }
}

Server Enable RCON

Initiate an RCON connection. You must already have a subscription/trial and organization.

POST /servers/{server_id}/rcon

Required Parameters

Name Type Description Example
data:attributes:metadata:betaSourceProtocol boolean Use new implementation of Source protocol. true
data:attributes:metadata:clientPerf boolean If client perf is enabled. true
data:attributes:metadata:connectionType string Connection type for Rust servers.
one of:"source" or "ws"
"source"
data:attributes:metadata:disableLocked nullable boolean If set to true RCON connection can not be enabled by the user. null
data:attributes:metadata:disabledReason nullable string Reason why the RCON connection is disabled. null
data:attributes:metadata:hasSourceMod nullable boolean If we have detected sourcemod. null
data:attributes:metadata:hllGetPlayerInfo boolean HLL. Control use of playerinfo command.
default: true
true
data:attributes:metadata:hllPlayerListInterval integer HLL. How often we should run get playerids and playerinfo commands.
default: 90
Range: 60 <= value <= 300
42
data:attributes:metadata:logSecret nullable string Log secret for Source games null
data:attributes:metadata:rconIP string Use a different IP for RCON connections "example"
data:attributes:metadata:reservedSlotKickReason string Kick message for the reserved slot system. "example"
data:attributes:metadata:reservedSlots integer The number of reserved slots for this server.
Range: 0 <= value
42
data:attributes:metadata:reservedSlotsKickLastToJoin boolean If the last player to join should be kicked when a player on the reserved slot list joins. true
data:attributes:metadata:statusInterval integer Rust. How often we should request server status via RCON.
Range: 15 <= value <= 300
42
data:attributes:metadata:useConnectionPool boolean HLL. Use a connection pool to increase command responsiveness. true
data:attributes:metadata:useGetChat boolean Ark & DNL. If we should use getchat, or getgamelog command. true
data:attributes:metadata:username string RCON username for RS2: Vietnam. "example"
data:attributes:portRCON integer Port to use for RCON connections. It is not possible to retrieve the RCON port. This is only used for updates.
Range: 10 <= value <= 65535
2302
data:attributes:rconPassword string Password to use for RCON connections. It is not possible to retrieve the password. This is only used for updates.
Length: 1..∞
"password"
data:id string unique identifier of server
pattern: \d+
"42"
data:relationships:defaultBanList:data string
data:relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
data:relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
data:type string Resource type. Always "server"
one of:"server"
"server"

Curl Example

$ curl -n -X POST https://api.battlemetrics.com/servers/$SERVER_ID/rcon \
  -d '{
  "data": {
    "type": "server",
    "id": "42",
    "attributes": {
      "portRCON": 2302,
      "rconPassword": "password",
      "metadata": {
      }
    },
    "relationships": {
      "defaultBanList": {
        "data": {
          "type": "banList",
          "id": "01234567-89ab-cdef-0123-456789abcdef"
        }
      },
      "organization": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      }
    }
  }
}' \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 204 No Content

Destroys the RCON connection and releases control of the server.

DELETE /servers/{server_id}/rcon

Curl Example

$ curl -n -X DELETE https://api.battlemetrics.com/servers/$SERVER_ID/rcon \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 204 No Content

Disconnects the RCON connection until manually connected.

DELETE /servers/{server_id}/rcon/disconnect

Curl Example

$ curl -n -X DELETE https://api.battlemetrics.com/servers/$SERVER_ID/rcon/disconnect \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 204 No Content

Connects the RCON connection until manually disconnected.

DELETE /servers/{server_id}/rcon/connect

Curl Example

$ curl -n -X DELETE https://api.battlemetrics.com/servers/$SERVER_ID/rcon/connect \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 204 No Content

Server info.

Only players and identifiers that are currently active will be included if requested.

The rcon:read scope is required to view private identifiers.

GET /servers/{server_id}

Optional Parameters

Name Type Description Example
fields:identifier string Request that only some attributes are returned "type,identifier"
fields:orgDescription string Request that only some attributes are returned "description,links"
fields:orgGroupDescription string Request that only some attributes are returned "description,links"
fields:organization string Request that only some attributes are returned "tz,banTemplate"
fields:player string Request that only some attributes are returned "updatedAt,name"
fields:server string Request that only some attributes are returned "name,ip,port"
fields:serverDescription string Request that only some attributes are returned "description,links"
fields:serverEvent string Request that only some attributes are returned "value"
fields:serverGroup string Request that only some attributes are returned "rank"
fields:serverUptime string Request that only some attributes are returned "value"
fields:session string Request that only some attributes are returned "start,stop"
include string Relations to include. Comma separated. Valid values: player, identifier, session, uptime:7, uptime:30, uptime:90, serverEvent, serverGroup, serverDescription, organization, orgDescription, orgGroupDescription.
Only public and approved descriptions will be returned. "player,identifier"
relations:identifier string Request that only some relationships are returned "a,b"
relations:orgDescription string Request that only some relationships are returned "a,b"
relations:orgGroupDescription string Request that only some relationships are returned "a,b"
relations:organization string Request that only some relationships are returned "a,b"
relations:player string Request that only some relationships are returned "a,b"
relations:server string Request that only some relationships are returned "a,b"
relations:serverDescription string Request that only some relationships are returned "a,b"
relations:serverEvent string Request that only some relationships are returned "a,b"
relations:serverGroup string Request that only some relationships are returned "a,b"
relations:serverUptime string Request that only some relationships are returned "a,b"
relations:session string Request that only some relationships are returned "a,b"

Curl Example

$ curl -n https://api.battlemetrics.com/servers/$SERVER_ID
 -G \
  -d include=player%2Cidentifier \
  -d fields[player]=updatedAt%2Cname \
  -d fields[server]=name%2Cip%2Cport \
  -d fields[identifier]=type%2Cidentifier \
  -d fields[session]=start%2Cstop \
  -d fields[serverUptime]=value \
  -d fields[serverEvent]=value \
  -d fields[serverGroup]=rank \
  -d fields[serverDescription]=description%2Clinks \
  -d fields[organization]=tz%2CbanTemplate \
  -d fields[orgDescription]=description%2Clinks \
  -d fields[orgGroupDescription]=description%2Clinks \
  -d relations[server]=a%2Cb \
  -d relations[player]=a%2Cb \
  -d relations[identifier]=a%2Cb \
  -d relations[session]=a%2Cb \
  -d relations[serverUptime]=a%2Cb \
  -d relations[serverEvent]=a%2Cb \
  -d relations[serverGroup]=a%2Cb \
  -d relations[serverDescription]=a%2Cb \
  -d relations[organization]=a%2Cb \
  -d relations[orgDescription]=a%2Cb \
  -d relations[orgGroupDescription]=a%2Cb

Response Example

HTTP/2.0 200 OK
{
  "data": {
    "type": "server",
    "id": "42",
    "attributes": {
      "id": "42",
      "name": "Server Name",
      "address": "play.example.com",
      "ip": "127.0.0.1",
      "port": 2302,
      "portQuery": 2303,
      "players": 42,
      "maxPlayers": 42,
      "rank": 42,
      "createdAt": "2015-01-01T12:00:00Z",
      "updatedAt": "2015-01-01T12:00:00Z",
      "location": [
        47.6140999,
        -122.1966574
      ],
      "country": "US",
      "status": "online",
      "details": null,
      "metadata": {
      },
      "rconActive": true,
      "queryStatus": null,
      "rconStatus": null,
      "rconLastConnected": "2015-01-01T12:00:00Z",
      "rconDisconnected": "2015-01-01T12:00:00Z",
      "private": false
    },
    "relationships": {
      "game": {
        "data": {
          "type": "game",
          "id": "ark"
        }
      }
    }
  },
  "included": [
    null
  ]
}

Player Count History

GET /servers/{server_id}/player-count-history

Required Parameters

Name Type Description Example
start date-time Time period start "2015-01-01T12:00:00Z"
stop date-time Time period stop "2015-01-01T12:00:00Z"

Optional Parameters

Name Type Description Example
resolution string Data resolution in minutes. Data retention raw: 2d, 30: 7d, 60: 30d, 1440: 180d
one of:"raw" or "30" or "60" or "1440"
"30"

Curl Example

$ curl -n https://api.battlemetrics.com/servers/$SERVER_ID/player-count-history
 -G \
  -d start=2015-01-01T12%3A00%3A00Z \
  -d stop=2015-01-01T12%3A00%3A00Z \
  -d resolution=30

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "type": "dataPoint",
      "attributes": {
        "timestamp": "2015-01-01T12:00:00Z",
        "group": 0,
        "name": "games.arma3.players",
        "max": 42,
        "value": 42,
        "min": 42
      }
    }
  ]
}

Rank History

GET /servers/{server_id}/rank-history

Required Parameters

Name Type Description Example
start date-time Time period start "2015-01-01T12:00:00Z"
stop date-time Time period stop "2015-01-01T12:00:00Z"

Curl Example

$ curl -n https://api.battlemetrics.com/servers/$SERVER_ID/rank-history
 -G \
  -d start=2015-01-01T12%3A00%3A00Z \
  -d stop=2015-01-01T12%3A00%3A00Z

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "type": "dataPoint",
      "attributes": {
        "timestamp": "2015-01-01T12:00:00Z",
        "group": 0,
        "name": "games.arma3.players",
        "max": 42,
        "value": 42,
        "min": 42
      }
    }
  ]
}

Group Rank History. The server must belong to a group.

GET /servers/{server_id}/group-rank-history

Required Parameters

Name Type Description Example
start date-time Time period start "2015-01-01T12:00:00Z"
stop date-time Time period stop "2015-01-01T12:00:00Z"

Curl Example

$ curl -n https://api.battlemetrics.com/servers/$SERVER_ID/group-rank-history
 -G \
  -d start=2015-01-01T12%3A00%3A00Z \
  -d stop=2015-01-01T12%3A00%3A00Z

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "type": "dataPoint",
      "attributes": {
        "timestamp": "2015-01-01T12:00:00Z",
        "group": 0,
        "name": "games.arma3.players",
        "max": 42,
        "value": 42,
        "min": 42
      }
    }
  ]
}

Time Played History

GET /servers/{server_id}/time-played-history

Required Parameters

Name Type Description Example
start date-time Time period start "2015-01-01T12:00:00Z"
stop date-time Time period stop "2015-01-01T12:00:00Z"

Curl Example

$ curl -n https://api.battlemetrics.com/servers/$SERVER_ID/time-played-history
 -G \
  -d start=2015-01-01T12%3A00%3A00Z \
  -d stop=2015-01-01T12%3A00%3A00Z

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "type": "dataPoint",
      "attributes": {
        "timestamp": "2015-01-01T12:00:00Z",
        "group": 0,
        "name": "games.arma3.players",
        "max": 42,
        "value": 42,
        "min": 42
      }
    }
  ]
}

First Time Player History

GET /servers/{server_id}/first-time-history

Required Parameters

Name Type Description Example
start date-time Time period start "2015-01-01T12:00:00Z"
stop date-time Time period stop "2015-01-01T12:00:00Z"

Curl Example

$ curl -n https://api.battlemetrics.com/servers/$SERVER_ID/first-time-history
 -G \
  -d start=2015-01-01T12%3A00%3A00Z \
  -d stop=2015-01-01T12%3A00%3A00Z

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "type": "dataPoint",
      "attributes": {
        "timestamp": "2015-01-01T12:00:00Z",
        "group": 0,
        "name": "games.arma3.players",
        "max": 42,
        "value": 42,
        "min": 42
      }
    }
  ]
}

Unique Player History

GET /servers/{server_id}/unique-player-history

Required Parameters

Name Type Description Example
start date-time Time period start "2015-01-01T12:00:00Z"
stop date-time Time period stop "2015-01-01T12:00:00Z"

Curl Example

$ curl -n https://api.battlemetrics.com/servers/$SERVER_ID/unique-player-history
 -G \
  -d start=2015-01-01T12%3A00%3A00Z \
  -d stop=2015-01-01T12%3A00%3A00Z

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "type": "dataPoint",
      "attributes": {
        "timestamp": "2015-01-01T12:00:00Z",
        "group": 0,
        "name": "games.arma3.players",
        "max": 42,
        "value": 42,
        "min": 42
      }
    }
  ]
}

Session History

GET /servers/{server_id}/relationships/sessions

Optional Parameters

Name Type Description Example
at date-time Used to view players that were online at a given time. "2015-01-01T12:00:00Z"
include string Relations to include. Comma separated. Valid values: player "player"
start date-time Used with stop to form a time period to view sessions from. "2015-01-01T12:00:00Z"
stop date-time Used with start to form a time period to view sessions from. "2015-01-01T12:00:00Z"

Curl Example

$ curl -n https://api.battlemetrics.com/servers/$SERVER_ID/relationships/sessions
 -G \
  -d start=2015-01-01T12%3A00%3A00Z \
  -d stop=2015-01-01T12%3A00%3A00Z \
  -d at=2015-01-01T12%3A00%3A00Z \
  -d include=player

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "type": "session",
      "attributes": {
        "start": "2015-01-01T12:00:00Z",
        "stop": "2015-01-01T12:00:00Z",
        "firstTime": true,
        "name": "Quark",
        "private": false,
        "metadata": [

        ]
      },
      "relationships": {
        "server": {
          "data": {
            "type": "server",
            "id": "42"
          }
        },
        "organization": {
          "data": {
            "type": "organization",
            "id": "42"
          }
        },
        "player": {
          "data": {
            "type": "player",
            "id": "42"
          }
        },
        "identifiers": {
          "data": [
            {
              "type": "identifier",
              "id": "example"
            }
          ]
        }
      }
    }
  ],
  "included": [
    null
  ]
}

Server Force Update

Force Update will cause us to immediately queue the server to be queried and updated. This is limited to subscribers and users who belong to the organization that owns the server if it is claimed.

This endpoint has a rate limit of once every 30 seconds per server, and 10 every five minutes per user.

POST /servers/{server_id}/force-update

Curl Example

$ curl -n -X POST https://api.battlemetrics.com/servers/$SERVER_ID/force-update \
  -H "Content-Type: application/json"

Response Example

HTTP/2.0 202
{
  "type": "server",
  "id": "42",
  "attributes": {
    "id": "42",
    "name": "Server Name",
    "address": "play.example.com",
    "ip": "127.0.0.1",
    "port": 2302,
    "portQuery": 2303,
    "players": 42,
    "maxPlayers": 42,
    "rank": 42,
    "createdAt": "2015-01-01T12:00:00Z",
    "updatedAt": "2015-01-01T12:00:00Z",
    "location": [
      47.6140999,
      -122.1966574
    ],
    "country": "US",
    "status": "online",
    "details": null,
    "metadata": {
    },
    "rconActive": true,
    "queryStatus": null,
    "rconStatus": null,
    "rconLastConnected": "2015-01-01T12:00:00Z",
    "rconDisconnected": "2015-01-01T12:00:00Z",
    "private": false
  },
  "relationships": {
    "game": {
      "data": {
        "type": "game",
        "id": "ark"
      }
    }
  }
}

Outage History. Outages are periods of time that the server did not respond to queries. Outage history stored and available for 90 days.

GET /servers/{server_id}/relationships/outages

Optional Parameters

Name Type Description Example
filter:range string Filter outages to by start timestamp.
pattern: ^((\d{4})(-(\d{2}))??(-(\d{2}))??(T(\d{2}):(\d{2})(:(\d{2}))??(\.(\d+))??(([\+\-]{1}\d{2}:\d{2})&#124;Z)??)??)?:((\d{4})(-(\d{2}))??(-(\d{2}))??(T(\d{2}):(\d{2})(:(\d{2}))??(\.(\d+))??(([\+\-]{1}\d{2}:\d{2})&#124;Z)??)??)?$
"2017-12-01T00:00:00Z:2017-12-31T00:00:00Z"
include string Relations to include. Comma separated. Valid values: uptime:7,uptime:30,uptime:90 "uptime:90"
page:key string Page key. The value to start from. The prev and next links provide this value automatically. It's recommended that you don't manually provide this value. "100"
page:rel string Direction. Next/prev records based on key.
one of:"next" or "prev"
"next"
page:size integer Number of items to return per page
default: 120
Range: 1 <= value <= 120
42

Curl Example

$ curl -n https://api.battlemetrics.com/servers/$SERVER_ID/relationships/outages
 -G \
  -d page[size]=42 \
  -d page[key]=100 \
  -d page[rel]=next \
  -d filter[range]=2017-12-01T00%3A00%3A00Z%3A2017-12-31T00%3A00%3A00Z \
  -d include=uptime%3A90

Response Example

HTTP/2.0 200 OK
{
  "meta": {
    "min": 42.0,
    "max": 42.0,
    "sum": 42.0,
    "count": 42.0,
    "onlineSince": "2015-01-01T12:00:00Z",
    "offlineSince": "2015-01-01T12:00:00Z",
    "lastPlayerJoin": "2015-01-01T12:00:00Z"
  },
  "data": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "type": "serverOutage",
      "attributes": {
        "start": "2015-01-01T12:00:00Z",
        "stop": "2015-01-01T12:00:00Z"
      },
      "relationships": {
        "server": {
          "data": {
            "type": "server",
            "id": "42"
          }
        }
      }
    }
  ],
  "included": [
    null
  ],
  "links": {
    "next": "https://api.battlemetrics.com/servers/1/relationships/outages?key=3a8cd808-2e8d-11b2-b96f-fb44c9b688db&rel=next",
    "prev": "https://api.battlemetrics.com/servers/1/relationships/outages?key=3a8cd808-2e8d-11b2-b96f-fb44c9b688db&rel=prev"
  }
}

Downtime History. Value is number of seconds the server was offline during that period. The default resolution provides daily values (1440 minutes).

GET /servers/{server_id}/relationships/downtime

Required Parameters

Name Type Description Example
start date-time Time period start "2015-01-01T12:00:00Z"
stop date-time Time period stop "2015-01-01T12:00:00Z"

Optional Parameters

Name Type Description Example
resolution string Data resolution in minutes. Data retention for 60 minutes is 90 days. Data is retained for the 1440 resolution indefinitely.
one of:"60" or "1440"
"60"

Curl Example

$ curl -n https://api.battlemetrics.com/servers/$SERVER_ID/relationships/downtime
 -G \
  -d start=2015-01-01T12%3A00%3A00Z \
  -d stop=2015-01-01T12%3A00%3A00Z \
  -d resolution=60

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "type": "dataPoint",
      "attributes": {
        "timestamp": "2015-01-01T12:00:00Z",
        "group": 0,
        "name": "games.arma3.players",
        "max": 42,
        "value": 42,
        "min": 42
      }
    }
  ]
}

Server Group

Stability: prototype

A server group provides a way of combining multiple servers that belong to the same cluster, report the same players, or otherwise similar/related.

Groups are assigned automatically and/or by BattleMetrics staff. Servers can not be added/removed from groups by users at this time.

There is no predefined hierarchy of servers in a group. A group leader is selected based on rank. The server with the best rank will be selected as the leader.

Attributes

Name Type Description Example
attributes:rank nullable integer Group rank. Can be null on new groups that haven't been ranked yet. 1
id uuid unique identifier of server group "01234567-89ab-cdef-0123-456789abcdef"
relationships:leader:data:id string unique identifier of server
pattern: \d+
"42"
relationships:leader:data:type string Resource type. Always "server"
one of:"server"
"server"
relationships:servers:data/id string unique identifier of server
pattern: \d+
"42"
relationships:servers:data/type string Resource type. Always "server"
one of:"server"
"server"
type string Resource type. Always "serverGroup"
one of:"serverGroup"
"serverGroup"

Session

Stability: prototype

A session represents a game play session on a server.

Attributes

Name Type Description Example
attributes:firstTime boolean True when this is the first time the player has been seen on the associated server. true
attributes:metadata/key string Metadata key, for example "ping", or "admin". "ping"
attributes:metadata/private boolean True when the associated metadata is private. true
attributes:metadata/value nullable string Metadata value. 100
attributes:name string The most recent name the player was seen using "Quark"
attributes:private boolean True when this session is associated with a private player profile. false
attributes:start date-time When the session started "2015-01-01T12:00:00Z"
attributes:stop nullable date-time When the session ended. If the value is null then the player is still online. null
id string unique identifier of session "01234567-89ab-cdef-0123-456789abcdef"
relationships:identifiers:data/id string Identifier ID
pattern: \d+
"example"
relationships:identifiers:data/type string Resource type. Always "identifier"
one of:"identifier"
"identifier"
relationships:organization:data:id string unique identifier of organization
pattern: \d+
"42"
relationships:organization:data:type string Resource type. Always "organization"
one of:"organization"
"organization"
relationships:player:data:id string unique identifier of player
pattern: \d+
"42"
relationships:player:data:type string Resource type. Always "player"
one of:"player"
"player"
relationships:server:data:id string unique identifier of server
pattern: \d+
"42"
relationships:server:data:type string Resource type. Always "server"
one of:"server"
"server"
type string Resource type. Always "session"
one of:"session"
"session"

Search for sessions by time range, player, and server. At least one filter must be provided.

GET /sessions

Optional Parameters

Name Type Description Example
fields:identifier string Request that only some attributes are returned "type,identifier"
fields:player string Request that only some attributes are returned "name,ip,port"
fields:server string Request that only some attributes are returned "name,ip,port"
fields:session string Request that only some attributes are returned "start,stop"
filter:at date-time Only show sessions that were active at the given time. Can not be combined with filter[range]. "2017-12-01T00:00:00Z"
filter:games string Comma separated list of game IDs "42"
filter:identifiers string Comma separated list of identifier IDs "42"
filter:organizations string Comma separated list of organization IDs "42"
filter:players string Comma separated list of player IDs "42"
filter:range string Filter sessions by start and stop timestamp. Start will be >= the start of the range and stop will be <= the end of the range. The start of the time range is required. Can not be combined with filter[at].
pattern: ^((\d{4})(-(\d{2}))??(-(\d{2}))??(T(\d{2}):(\d{2})(:(\d{2}))??(\.(\d+))??(([\+\-]{1}\d{2}:\d{2})&#124;Z)??)??):((\d{4})(-(\d{2}))??(-(\d{2}))??(T(\d{2}):(\d{2})(:(\d{2}))??(\.(\d+))??(([\+\-]{1}\d{2}:\d{2})&#124;Z)??)??)?$
"2017-12-01T00:00:00Z:2017-12-31T00:00:00Z"
filter:servers string Comma separated list of server IDs "42"
include string Relations to include. Comma separated. Valid: player, identifier, server "identifier"
page:key string Page key. The value to start from. The prev and next links provide this value automatically. It's recommended that you don't manually provide this value. "100"
page:rel string Direction. Next/prev records based on key.
one of:"next" or "prev"
"next"
page:size integer Number of items to return per page
default: 10
Range: 1 <= value <= 100
42

Curl Example

$ curl -n https://api.battlemetrics.com/sessions
 -G \
  -d filter[servers]=42 \
  -d filter[games]=42 \
  -d filter[organizations]=42 \
  -d filter[players]=42 \
  -d filter[identifiers]=42 \
  -d filter[range]=2017-12-01T00%3A00%3A00Z%3A2017-12-31T00%3A00%3A00Z \
  -d filter[at]=2017-12-01T00%3A00%3A00Z \
  -d page[size]=42 \
  -d page[key]=100 \
  -d page[rel]=next \
  -d include=identifier \
  -d fields[session]=start%2Cstop \
  -d fields[identifier]=type%2Cidentifier \
  -d fields[server]=name%2Cip%2Cport \
  -d fields[player]=name%2Cip%2Cport

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "type": "session",
      "attributes": {
        "start": "2015-01-01T12:00:00Z",
        "stop": "2015-01-01T12:00:00Z",
        "firstTime": true,
        "name": "Quark",
        "private": false,
        "metadata": [

        ]
      },
      "relationships": {
        "server": {
          "data": {
            "type": "server",
            "id": "42"
          }
        },
        "organization": {
          "data": {
            "type": "organization",
            "id": "42"
          }
        },
        "player": {
          "data": {
            "type": "player",
            "id": "42"
          }
        },
        "identifiers": {
          "data": [
            {
              "type": "identifier",
              "id": "example"
            }
          ]
        }
      }
    }
  ],
  "included": [

  ],
  "links": {
    "next": "https://api.battlemetrics.com/sessions?page[key]=2016-10-05T14:35:51.962Z&page[rel]=next",
    "prev": "https://api.battlemetrics.com/sessions?page[key]=2015-10-05T14:35:51.962Z&page[rel]=prev"
  }
}

Get details on a specific session by id.

GET /sessions

Optional Parameters

Name Type Description Example
fields:identifier string Request that only some attributes are returned "type,identifier"
fields:player string Request that only some attributes are returned "name,ip,port"
fields:server string Request that only some attributes are returned "name,ip,port"
fields:session string Request that only some attributes are returned "start,stop"
include string Relations to include. Comma separated. Valid: player, identifier, server "identifier"

Curl Example

$ curl -n https://api.battlemetrics.com/sessions
 -G \
  -d include=identifier \
  -d fields[session]=start%2Cstop \
  -d fields[identifier]=type%2Cidentifier \
  -d fields[server]=name%2Cip%2Cport \
  -d fields[player]=name%2Cip%2Cport

Response Example

HTTP/2.0 200 OK
{
  "data": {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    "type": "session",
    "attributes": {
      "start": "2015-01-01T12:00:00Z",
      "stop": "2015-01-01T12:00:00Z",
      "firstTime": true,
      "name": "Quark",
      "private": false,
      "metadata": [

      ]
    },
    "relationships": {
      "server": {
        "data": {
          "type": "server",
          "id": "42"
        }
      },
      "organization": {
        "data": {
          "type": "organization",
          "id": "42"
        }
      },
      "player": {
        "data": {
          "type": "player",
          "id": "42"
        }
      },
      "identifiers": {
        "data": [
          {
            "type": "identifier",
            "id": "example"
          }
        ]
      }
    }
  },
  "included": [

  ]
}

Returns a list of sessions that were active during the same time as the provided session id.

GET /sessions/{session_id}/relationships/coplay

Optional Parameters

Name Type Description Example
fields:identifier string Request that only some attributes are returned "type,identifier"
fields:player string Request that only some attributes are returned "name,ip,port"
fields:server string Request that only some attributes are returned "name,ip,port"
fields:session string Request that only some attributes are returned "start,stop"
include string Relations to include. Comma separated. Valid: player, identifier, server "identifier"
page:key string Page key. The value to start from. The prev and next links provide this value automatically. It's recommended that you don't manually provide this value. "100"
page:offset integer Page offset
Range: 0 <= value <= 1000
"50"
page:rel string Direction. Next/prev records based on key.
one of:"next" or "prev"
"next"
page:size integer Number of items to return per page
default: 10
Range: 1 <= value <= 100
42

Curl Example

$ curl -n https://api.battlemetrics.com/sessions/$SESSION_ID/relationships/coplay
 -G \
  -d page[size]=42 \
  -d page[key]=100 \
  -d page[offset]=50 \
  -d page[rel]=next \
  -d include=identifier \
  -d fields[session]=start%2Cstop \
  -d fields[identifier]=type%2Cidentifier \
  -d fields[server]=name%2Cip%2Cport \
  -d fields[player]=name%2Cip%2Cport

Response Example

HTTP/2.0 200 OK
{
  "data": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "type": "session",
      "attributes": {
        "start": "2015-01-01T12:00:00Z",
        "stop": "2015-01-01T12:00:00Z",
        "firstTime": true,
        "name": "Quark",
        "private": false,
        "metadata": [

        ]
      },
      "relationships": {
        "server": {
          "data": {
            "type": "server",
            "id": "42"
          }
        },
        "organization": {
          "data": {
            "type": "organization",
            "id": "42"
          }
        },
        "player": {
          "data": {
            "type": "player",
            "id": "42"
          }
        },
        "identifiers": {
          "data": [
            {
              "type": "identifier",
              "id": "example"
            }
          ]
        }
      }
    }
  ],
  "included": [

  ],
  "links": {
    "next": "https://api.battlemetrics.com/sessions/dd6b1a60-f29a-11e9-a987-573e55219a58/relationships/coplay?page[key]=2016-10-05T14:35:51.962Z&page[rel]=next",
    "prev": "https://api.battlemetrics.com/sessions/dd6b1a60-f29a-11e9-a987-573e55219a58/relationships/coplay?page[key]=2015-10-05T14:35:51.962Z&page[rel]=prev"
  }
}

User

Stability: prototype

User id ane nickname.

Attributes

Name Type Description Example
attributes:id string unique identifier of user
pattern: \d+
"42"
attributes:nickname nullable string Nickname for user. Nicknames are not unique, and may change at any time. "Sisko"
id string unique identifier of user
pattern: \d+
"42"
relationships:organizations:data/id string unique identifier of organization
pattern: \d+
"42"
relationships:organizations:data/type string Resource type. Always "organization"
one of:"organization"
"organization"
type string Resource type. Always "user"
one of:"user"
"user"