BULLETMETA

Developers

A typed API over servers that count toward stats, their matches, players, boards and clans — plus your own organization's records, and the two lists your own tooling has to keep in step: the whitelist and the ban list. Available on the Enterprise plan.

Quickstart

Every method is a POST of a JSON body to /package.Service/Method on https://api.bulletmeta.app. That is the Connect protocol; the same endpoints speak gRPC and gRPC-Web.

curl https://api.bulletmeta.app/bulletmeta.api.v1.ServerService/GetLiveStatus \
  -H "Authorization: Bearer $BULLETMETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"serverId": "…"}'

Streaming needs a real gRPC client — with buf curl:

buf curl --protocol grpc --http2-prior-knowledge \
  -H "Authorization: Bearer $BULLETMETA_API_KEY" \
  -d '{"serverId": "…"}' \
  https://api.bulletmeta.app/bulletmeta.api.v1.ServerService/WatchLiveStatus

Generated SDKs come from the schema on the Buf Schema Registry:

# Go
go get buf.build/gen/go/bulletmeta/api/connectrpc/go

# TypeScript (connect-es v2): generate the message types, then
# createClient(ServerService, transport) from @connectrpc/connect.
# Keep the plugin's minor in step with your @bufbuild/protobuf.
npm i @bufbuild/protobuf @connectrpc/connect @connectrpc/connect-web
buf generate buf.build/bulletmeta/api --template '{"version":"v2","plugins":[{"remote":"buf.build/bufbuild/es","out":"gen","opt":["target=ts"]}]}'

@buf/bulletmeta_api.connectrpc_es is a connect-es v1 artifact; on v2 you only need the bufbuild/es output above. For other generators the OpenAPI document carries the base URL and the bearer scheme.

To learn which organization a key belongs to — the id the organization filters take — ask the key:

curl https://api.bulletmeta.app/bulletmeta.api.v1.KeyService/GetKeyInfo \
  -H "Authorization: Bearer $BULLETMETA_API_KEY" \
  -H "Content-Type: application/json" -d '{}'

API keys

A key belongs to one organization and is created by its owner under Settings → API. The token bm_live_<prefix>_<secret> is shown once and only its SHA-256 is stored, so a lost key is replaced rather than recovered. Up to 25 active keys, expiry from 1 to 730 days, and a revocation takes effect within 60 seconds.

Authorization: Bearer bm_live_…

Scopes

ScopeWhat it opens
public:readEverything except OrgService, plus your own organization's servers and their matches.
org:readOrgService reads: sanctions, whitelist, audit log, members, playtime and seeding, seeding standings.
lists:writeOrgService writes: whitelist grants, bans, sanction evidence, finalize and lift.

There is no organization parameter anywhere: a key acts on the organization it belongs to. Anything it may not see answers not_found, which is indistinguishable from something that does not exist.

Rate limiting

10 requests a second per key, bursting to 100. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset; over the limit is HTTP 429 with Retry-After in seconds. It is a continuously refilling token bucket, not a fixed window. If the limiter's own store is unavailable it fails open: a response without the headers was not measured, which does not mean there is no limit.

for attempt in 1 2 3 4 5; do
  sleep $(( 2 ** attempt ))   # and honour Retry-After when it is larger
done

Pagination

List methods take pageSize and answer with nextPageToken. Send it back as pageToken for the next page; an empty token is the end. Tokens are opaque keyset cursors — do not parse or build one.

Page sizes differ by method, so send one rather than relying on the default (default / maximum):

ListServers, ListMatches, ListPlayerMatches25 / 100
GetBoard50 / 100
ClanService.ListMembers, every OrgService list50 / 200
GetRatingHistory100 / 500
ListMatchKills200 / 500

What the data means

Live status. STATUS_ONLINE is any tile that exists. It is STATUS_STALE when lastHeartbeatAt is more than 90 seconds old — "not heard from", not "down". STATUS_OFFLINE is a tile with a problem, or no tile at all: a visible server that has never reported answers OFFLINE, not not_found. STATUS_CHANGING_MAP wins over the rest for up to three minutes after a round ends. The tile is rewritten about every five seconds and never carries a roster. WatchLiveStatus sends the tile, every update, and — re-checking every 30 seconds — the STALE or OFFLINE of a server that stopped reporting.

Visibility. A key sees a server that counts toward public stats on an active community, or one of its own organization's. Anything else is not_found, deliberately indistinguishable from a record that does not exist. Matches in which nothing happened (no score, no kills) are not listed.

Playtime. totalSeconds includes the running session measured to now, so it grows between two calls. lastConnectedAt is the start of the latest session — label it "last connected", never "last seen". An unknown SteamID64 is not_found; a known player who never joined a matching server is an empty servers with zeros, not an error.

Narrowing lists. ListServers takes organizationId; ListPlayerMatches takes serverId and organizationId. Every Match carries serverName, so a list needs no second call to be labelled.

JSON. Over the Connect JSON protocol int64 fields are strings and enums are their names ("STATUS_ONLINE"). With @bufbuild/protobuf an int64 is a bigint; convert it before arithmetic.

Caching. Responses carry no cache headers. Cache on your side: a 10-second TTL on the live tile costs at most two updates of staleness and keeps a busy page to one call per server.

Errors

Errors are Connect codes, with the HTTP status a Connect client maps them to:

unauthenticated (401)Missing, malformed, expired or revoked key.
permission_denied (403)The key lacks the scope this method needs.
not_found (404)No such record, or one this key may not see.
invalid_argument (400)A field is missing or out of range.
failed_precondition (412)The record is not in a state that allows this, such as a finalized sanction.
resource_exhausted (429)Rate limited; retry after Retry-After.
unavailable (503)A dependency is down. Retry with backoff.

Idempotent writes

Every write takes a requestId. Retrying with the same one returns the first response instead of writing again, for 24 hours — so a timeout you did not see the answer to is safe to repeat.

curl https://api.bulletmeta.app/bulletmeta.api.v1.OrgService/CreateWhitelistGrant \
  -H "Authorization: Bearer $BULLETMETA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject": "76561198000000000", "requestId": "seed-2026-09-16-01"}'

A write that was saved but could not be pushed to a game server answers with warnings and no error: the record exists, and retrying would write it twice. Every write is audited as your key, and shows in the console's audit log as "API key ‹name›".

Versioning

The schema is bulletmeta.api.v1, published on buf.build/bulletmeta/api. Fields are added, never renumbered or removed — every change runs through buf breaking. A breaking change would be a new package, never an edit to v1.

Reference

ClanService

Clans' public pages.

POST/bulletmeta.api.v1.ClanService/GetClan

Request

slugstring

Response

clanClan

POST/bulletmeta.api.v1.ClanService/ListMembers

Request

slugstring
pageSizeinteger
pageTokenstring

Response

membersClanMember[]
nextPageTokenstring

KeyService

The key itself.

POST/bulletmeta.api.v1.KeyService/GetKeyInfo

Which organization the calling key belongs to, and what it may do. Needs only `public:read`, so any key can find its own organization id for the filters that take one.

Request

No fields.

Response

keyIdstring
organizationIdstring
organizationNamestring
scopesstring[]`public:read`, `org:read`, `lists:write`.

LeaderboardService

The public boards, as bulletmeta.app/stats ranks them.

POST/bulletmeta.api.v1.LeaderboardService/GetBoard

Request

categoryBoardCategory
pageSizeinteger1–100; 0 means 50. The board holds the top 1000.
pageTokenstring
seasonstringA season (`s2`, see ListSeasons). Empty is the lifetime board, as before. The rating board is never seasonal and ignores it.

Response

entriesBoardEntry[]
nextPageTokenstring

POST/bulletmeta.api.v1.LeaderboardService/ListSeasons

Request

No fields.

Response

seasonsSeason[]

MatchService

Finished matches on servers visible to the key.

POST/bulletmeta.api.v1.MatchService/GetMatch

Request

matchIdstring

Response

matchMatch
resultsMatchResult[]

POST/bulletmeta.api.v1.MatchService/ListMatchKills

Oldest first, as a timeline.

Request

matchIdstring
pageSizeinteger1–500; 0 means 200.
pageTokenstring

Response

killsKill[]
nextPageTokenstring

POST/bulletmeta.api.v1.MatchService/ListMatches

Newest first.

Request

serverIdstringOnly this server's matches, when set.
pageSizeinteger
pageTokenstring

Response

matchesMatch[]
nextPageTokenstring

OrgService

The key's own organization. Reads need the `org:read` scope and writes need `lists:write`; there is no organization parameter on either, because a key only ever touches the organization it belongs to. Every write is audited as the key itself, and takes a `request_id` so a retried call returns the first result instead of writing twice.

POST/bulletmeta.api.v1.OrgService/AddSanctionEvidence

Appends evidence URLs to a sanction that is neither finalized nor lifted; a URL the sanction already holds is not added again.

Request

sanctionIdstring
evidenceUrlsstring[]Absolute https URLs of at most 2048 bytes, added after the ones the sanction already has; a sanction holds at most 50.
requestIdstring

Response

sanctionSanction

POST/bulletmeta.api.v1.OrgService/ChangeBanExpiry

Moves when a ban ends, finalized or not; the reason and evidence stay. Refused for a lifted or lapsed ban and for one held by a pending or accepted platform-list nomination.

Request

sanctionIdstring
expiresAtgoogle.protobuf.TimestampThe new end, in the future. Unset makes the ban permanent.
reasonstringWhy it moves; required, recorded in the audit log and the moderation post.
requestIdstring

Response

sanctionSanction
warningsstring[]

POST/bulletmeta.api.v1.OrgService/CreateBan

A ban is refused with `already_exists`, naming the existing sanction, while a live ban of the same player already covers the scope: an org-wide one covers every server, a per-server one only its own.

Request

steamIdstring
serverIdstringUnset bans on every server of the organization.
reasonstring
notesstring
evidenceUrlsstring[]Without evidence the ban applies but stays open ("needs evidence").
expiresAtgoogle.protobuf.Timestamp
requestIdstring

Response

sanctionSanction
warningsstring[]

POST/bulletmeta.api.v1.OrgService/CreateWhitelistGrant

Writes (`lists:write`).

Request

subjectstringA SteamID64 or a BulletMeta profile id. The profile is created for an unknown SteamID64, exactly as a join would create it.
serverIdstringUnset grants on every server of the organization, now and future.
notestring
expiresAtgoogle.protobuf.TimestampUnset is open-ended. The game has no expiry, so BulletMeta enforces one by leaving the SteamID out of the next push.
requestIdstringRepeat a call safely: the same id returns the first call's grant.

Response

grantWhitelistGrant
warningsstring[]Servers the push did not reach. The grant is written either way.

POST/bulletmeta.api.v1.OrgService/FinalizeSanction

Request

sanctionIdstring
requestIdstring

Response

sanctionSanction

POST/bulletmeta.api.v1.OrgService/LiftSanction

Request

sanctionIdstring
reasonstring
requestIdstring

Response

sanctionSanction
warningsstring[]

POST/bulletmeta.api.v1.OrgService/ListAuditLog

Request

pageSizeinteger
pageTokenstring

Response

entriesAuditEntry[]
nextPageTokenstring

POST/bulletmeta.api.v1.OrgService/ListEventResponses

One event's answers and, once computed, who was actually there.

Request

eventIdstring

Response

responsesEventResponse[]
attendanceEventAttendance[]Empty until the attendance sweep has run, an hour after the end.
attendanceComputedAtgoogle.protobuf.Timestamp

POST/bulletmeta.api.v1.OrgService/ListEvents

The organization's events, newest start first.

Request

pageSizeinteger
pageTokenstring
publishedOnlybooleanOnly published events; drafts and cancelled ones are left out.

Response

eventsEvent[]
nextPageTokenstring

POST/bulletmeta.api.v1.OrgService/ListOrgMembers

Request

pageSizeinteger
pageTokenstring

Response

membersOrgMember[]
nextPageTokenstring

POST/bulletmeta.api.v1.OrgService/ListPlayerPresence

Playtime and seeding time per player, for the key's own servers.

Request

pageSizeinteger
pageTokenstring
serverIdstringOne of the key's own servers; unset covers every one of them.
fromgoogle.protobuf.Timestamp
togoogle.protobuf.Timestamp

Response

playersPlayerPresence[]
nextPageTokenstring

POST/bulletmeta.api.v1.OrgService/ListSanctions

Request

pageSizeinteger
pageTokenstring

Response

sanctionsSanction[]
nextPageTokenstring

POST/bulletmeta.api.v1.OrgService/ListSeedingStandings

Where players stand under the organization's seeding whitelist rules.

Request

pageSizeinteger
pageTokenstring
ruleIdstringOne rule; unset covers every rule of the organization.

Response

standingsSeedingStanding[]
nextPageTokenstring

POST/bulletmeta.api.v1.OrgService/ListWhitelist

Request

pageSizeinteger
pageTokenstring
includeRevokedbooleanInclude revoked and expired grants; without it only active ones are listed.

Response

grantsWhitelistGrant[]
nextPageTokenstring

POST/bulletmeta.api.v1.OrgService/RevokeWhitelistGrant

Request

grantIdstring
requestIdstring

Response

grantWhitelistGrant
warningsstring[]

PlayerService

Player careers, from counted matches on enrolled servers.

POST/bulletmeta.api.v1.PlayerService/GetCareerStats

Request

playerPlayerSelector
seasonstringA season (`s2`, see LeaderboardService.ListSeasons). Empty is the lifetime totals, as before. The counters are that season's; the rating is the current one either way.

Response

statsCareerStats

POST/bulletmeta.api.v1.PlayerService/GetPlayer

Request

playerPlayerSelector

Response

playerPlayerRef
createdAtgoogle.protobuf.Timestamp

POST/bulletmeta.api.v1.PlayerService/GetPlaytime

Request

playerPlayerSelector
serverIdstringOnly this server's sessions, when set.
organizationIdstringOnly sessions on this organization's servers, when set.

Response

totalSecondsintegerstringThe sum over `servers`; grows between calls while the player is online.
onlineboolean
lastConnectedAtgoogle.protobuf.TimestampThe start of the latest session, not a last-seen time.
serversServerPlaytime[]Most played first.

POST/bulletmeta.api.v1.PlayerService/GetRatingHistory

Request

playerPlayerSelector
pageSizeinteger1–500; 0 means 100. Newest first.
pageTokenstring

Response

pointsRatingPoint[]
nextPageTokenstring

POST/bulletmeta.api.v1.PlayerService/GetWeaponStats

Request

playerPlayerSelector

Response

weaponsWeaponStat[]

POST/bulletmeta.api.v1.PlayerService/ListPlayerMatches

Request

playerPlayerSelector
pageSizeinteger1–100; 0 means 25.
pageTokenstring
serverIdstringOnly matches on this server, when set.
organizationIdstringOnly matches on this organization's servers, when set.

Response

matchesPlayerMatch[]
nextPageTokenstring

ServerService

Game servers: enrolled (public) servers, plus the key's own organization's.

POST/bulletmeta.api.v1.ServerService/GetLiveStatus

The live tile: status, map, players, scores. No roster.

Request

serverIdstring

Response

liveStatusLiveStatus

POST/bulletmeta.api.v1.ServerService/GetServer

Request

serverIdstring

Response

serverServer

POST/bulletmeta.api.v1.ServerService/ListServers

Servers visible to the key, by name.

Request

pageSizeinteger1–100; 0 means 25.
pageTokenstring
organizationIdstringOnly this organization's servers, when set. `KeyService.GetKeyInfo` names the key's own.

Response

serversServer[]
nextPageTokenstring

STREAM/bulletmeta.api.v1.ServerService/WatchLiveStatus

Server stream: the server's live tile, then every update as it is published. gRPC, gRPC-Web or Connect streaming — not plain JSON over POST.