API Documentation

External API endpoints for bans.live

Base URL

All API endpoints are available at:

https://bans.live/api

Endpoints

POST

/api/track

Add Player to Tracking

Adds a player to the tracking queue for monitoring ban status.

Parameters

steamId

string

Required

Steam ID, Steam ID64, or Steam profile URL

Request Body

{
  "steamId": "string"
}

Response

{
  "success": true,
  "message": "Player added to tracking queue"
}

Error Response

{
  "error": "steamId is required"
}

GET

/api/bans

Get Latest Bans

Retrieves the latest bans with optional filtering.

Parameters

time

stringDefault: today

Time filter - 'today', 'week', 'month'

limit

numberDefault: 10Max: 100

Number of results

type

stringDefault: all

Ban type filter - 'all', 'vac', 'game', 'community', 'economy'

Example Request

GET /api/bans?time=week&limit=20&type=vac

Response

{
  "success": true,
  "data": [
    {
      "id": "string",
      "player": {
        "steamId64": "string",
        "username": "string",
        "avatarUrl": "string",
        "level": 0
      },
      "banType": "VAC",
      "detectedAt": "2024-01-01T00:00:00.000Z",
      "isRemoval": false,
      "games": "string"
    }
  ],
  "meta": {
    "count": 20,
    "timeFilter": "week",
    "type": "vac",
    "limit": 20
  }
}

GET

/api/leaderboard

Get Leaderboard

Retrieves the leaderboard of banned players. Only players with actual ban history records (tracked bans) are included in the results.

Parameters

type

stringDefault: all

Ban type filter - 'all', 'vac', 'game', 'community', 'economy'

limit

numberDefault: 100Max: 1000

Number of results

Example Request

GET /api/leaderboard?type=vac&limit=50

Response

{
  "success": true,
  "data": [
    {
      "id": "string",
      "steamId64": "string",
      "username": "string",
      "avatarUrl": "string",
      "level": 0,
      "bans": {
        "vac": true,
        "game": false,
        "community": false,
        "economy": false,
        "vacCount": 1,
        "gameCount": 0
      },
      "bannedAt": "2024-01-01T00:00:00.000Z",
      "addedAt": "2024-01-01T00:00:00.000Z",
      "latestBan": {
        "banType": "VAC",
        "detectedAt": "2024-01-01T00:00:00.000Z",
        "games": "string"
      }
    }
  ],
  "meta": {
    "count": 50,
    "type": "vac",
    "limit": 50
  }
}

Data Types

Ban Types

VACValve Anti-Cheat ban

GAMEGame ban

COMMUNITYCommunity ban

ECONOMYEconomy ban

Error Handling

All endpoints return appropriate HTTP status codes:

200

Success

400

Bad Request (invalid parameters)

500

Internal Server Error

Error responses follow this format:

{
  "error": "Error message"
}