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
- Rate Limits
- References
- Scopes
- Sorting
- Sparse fieldsets
- API Endpoints
- Ban
- Ban List Exemption
- Ban List
- Ban List Invite
- Native Ban
- Commands Activity
- Coplay
- Data Point
- Flag Player
- Game
- Game Features
- Game Feature Options
- Player Identifier
- Leaderboard
- Organization
- Organization Friend
- Organization Stats
- Player
- Player Counter
- Player Flag
- Player Note
- Player Stats
- Related Player Identifier
- Reserved Slot
- Server
- Server List
- Server Create
- Server Update
- Server Enable RCON
- Server Delete RCON
- Server RCON Disconnect
- Server RCON Connect
- Server Info
- Server Player Count History
- Server Rank History
- Server Group Rank History
- Server Time Played History
- Server First Time History
- Server Unique Player History
- Server Session History
- Server Force Update
- Server Outage History
- Server Downtime History
- Server Group
- Session
- User
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"
}
}
}
}
Ban Export
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
Ban Delete
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
Ban Info
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
]
}
Ban List
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"
}
}
Ban Update
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"
}
}
}
}
}
Ban List Exemption Read
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"
}
}
}
}
}
Ban List Exemption List Exemptions
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"
}
}
}
}
]
}
Ban List Exemption Update
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
Ban List Exemption Delete
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"
}
}
}
}
}
Ban List List
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"
}
}
Ban List Organization List
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"
}
}
Ban List Read Organization's Subscription
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": [
]
}
Ban List Read
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": [
]
}
Ban List Update
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
Ban List Unsubscribe
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"
}
}
}
}
}
Ban List Invite Read
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": [
]
}
Ban List Invite List invites.
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"
}
}
Ban List Invite Delete
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" |
Native Ban List
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" |
Commands Activity List
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})|Z)??)??)?:((\d{4})(-(\d{2}))??(-(\d{2}))??(T(\d{2}):(\d{2})(:(\d{2}))??(\.(\d+))??(([\+\-]{1}\d{2}:\d{2})|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" |
Coplay List
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})|Z)??)??)?:((\d{4})(-(\d{2}))??(-(\d{2}))??(T(\d{2}):(\d{2})(:(\d{2}))??(\.(\d+))??(([\+\-]{1}\d{2}:\d{2})|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" |
Data Point List
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})|Z)??)??):((\d{4})(-(\d{2}))??(-(\d{2}))??(T(\d{2}):(\d{2})(:(\d{2}))??(\.(\d+))??(([\+\-]{1}\d{2}:\d{2})|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"
}
}
}
}
]
}
Flag Player Flags
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"
}
}
Flag Player Delete
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" |
Game List
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"
}
}
Game Info
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" |
Game Features List
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" |
Game Feature Options List
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 List
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" |
Organization Player Stats
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})|Z)??)??):((\d{4})(-(\d{2}))??(-(\d{2}))??(T(\d{2}):(\d{2})(:(\d{2}))??(\.(\d+))??(([\+\-]{1}\d{2}:\d{2})|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" |
Organization Friend List
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"
}
}
Organization Friend Organization Friend
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": [
]
}
Organization Friend Update Settings
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 Bulk update Settings
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"
}
]
}
}
}
}
Organization Friend Delete
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
Organization Friend Bulk Delete
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" |
Player List
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})|Z)??)??)?:((\d{4})(-(\d{2}))??(-(\d{2}))??(T(\d{2}):(\d{2})(:(\d{2}))??(\.(\d+))??(([\+\-]{1}\d{2}:\d{2})|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})|Z)??)??)?:((\d{4})(-(\d{2}))??(-(\d{2}))??(T(\d{2}):(\d{2})(:(\d{2}))??(\.(\d+))??(([\+\-]{1}\d{2}:\d{2})|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
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
]
}
Player Time Played History
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
}
}
]
}
Player Server Information
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"
}
}
Player Session History
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"
}
}
}
}
}
Player Flag Delete
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
Player Flag Info
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"
}
}
}
}
}
Player Flag List
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"
}
}
Player Flag Update
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"
}
}
}
}
}
Player Note Delete
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
Player Note Info
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": [
]
}
Player Note List
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"
}
}
Player Note Update
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" |
Related Player Identifier Info
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"
}
}
}
}
}
Reserved Slot Delete
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
Reserved Slot Info
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
]
}
Reserved Slot List
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"
}
}
Reserved Slot Update
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" |
Server List
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"
}
}
}
}
}
Server Update
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
Server Delete RCON
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
Server RCON Disconnect
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
Server RCON Connect
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
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
]
}
Server Player Count History
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
}
}
]
}
Server Rank History
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
}
}
]
}
Server Group Rank History
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
}
}
]
}
Server Time Played History
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
}
}
]
}
Server First Time History
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
}
}
]
}
Server Unique Player History
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
}
}
]
}
Server Session History
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"
}
}
}
}
Server Outage History
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})|Z)??)??)?:((\d{4})(-(\d{2}))??(-(\d{2}))??(T(\d{2}):(\d{2})(:(\d{2}))??(\.(\d+))??(([\+\-]{1}\d{2}:\d{2})|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"
}
}
Server Downtime History
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" |
Session Sessions
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})|Z)??)??):((\d{4})(-(\d{2}))??(-(\d{2}))??(T(\d{2}):(\d{2})(:(\d{2}))??(\.(\d+))??(([\+\-]{1}\d{2}:\d{2})|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"
}
}
Session Session Details
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": [
]
}
Session Sessions CoPlay
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" |