API Documentation

Comprehensive guide to the TF2 Price DB RESTful API

🏠 Back to Home

📋 General Information

🔌 Main API Endpoints

GET /api/

Health check. Returns status of API and database connectivity.

Response
{
  "status": "ok",
  "db": "ok"
}

Example: /api/

GET /api/items

Returns a list of all unique items (name and SKU) in the database.

Response
[
  {
    "name": "Strange Professional Killstreak Backburner",
    "sku": "40;11;kt-3"
  }
]

Example: /api/items

GET /api/latest-prices

Returns the latest price entry for each SKU.

Response
[
  {
    "name": "Strange Professional Killstreak Backburner",
    "sku": "40;11;kt-3",
    "source": "bptf",
    "time": 1748874425,
    "buy": {
      "keys": 4,
      "metal": 11.33
    },
    "sell": {
      "keys": 4,
      "metal": 69.22
    }
  }
]

Example: /api/latest-prices

GET /api/prices

Returns paginated price history with metadata. Use limit and offset query parameters for pagination.

Parameters
Parameter Type Description
limit number Maximum number of records to return (default: 100, max: 1000) (optional)
offset number Number of records to skip (default: 0) (optional)
Response
[
  {
    "name": "Strange Professional Killstreak Backburner",
    "sku": "40;11;kt-3",
    "source": "bptf",
    "time": 1748874425,
    "buy": {
      "keys": 4,
      "metal": 11.33
    },
    "sell": {
      "keys": 4,
      "metal": 69.22
    }
  }
]

Example: /api/prices?limit=50&offset=0

GET /api/item/:sku

Returns the latest price for a specific item SKU.

Parameters
Parameter Type Description
sku string The SKU of the item to look up
Response
{
  "name": "Strange Professional Killstreak Backburner",
  "sku": "40;11;kt-3",
  "source": "bptf",
  "time": 1748874425,
  "buy": {
    "keys": 4,
    "metal": 11.33
  },
  "sell": {
    "keys": 4,
    "metal": 69.22
  }
}

Example: /api/item/40;11;kt-3

GET /api/item-history/:sku

Returns the full price history for a specific item SKU as an array. Optionally filter by start and/or end unix timestamps.

Parameters
Parameter Type Description
sku string The SKU of the item to look up
start number (optional) Only include entries after this unix timestamp (optional)
end number (optional) Only include entries before this unix timestamp (optional)
Response
[
  {
    "name": "Strange Professional Killstreak Backburner",
    "sku": "40;11;kt-3",
    "source": "bptf",
    "time": 1748874425,
    "buy": {
      "keys": 4,
      "metal": 11.33
    },
    "sell": {
      "keys": 4,
      "metal": 69.22
    }
  }
]

Example: /api/item-history/40;11;kt-3?start=1700000000&end=1800000000

GET /api/item-stats/:sku

Returns statistics for a specific item SKU (min, max, avg, count) for buy and sell prices.

Parameters
Parameter Type Description
sku string The SKU of the item to look up
Response
{
  "buy": {
    "count": 12,
    "keys": {
      "min": 2,
      "max": 4,
      "avg": 3.1
    },
    "metal": {
      "min": 11.33,
      "max": 69.22,
      "avg": 40.12
    }
  },
  "sell": {
    "count": 12,
    "keys": {
      "min": 2,
      "max": 4,
      "avg": 3.1
    },
    "metal": {
      "min": 11.33,
      "max": 69.22,
      "avg": 40.12
    }
  }
}

Example: /api/item-stats/40;11;kt-3

GET /api/graph/:sku

Returns an HTML page with a price history chart for a specific item SKU.

Parameters
Parameter Type Description
sku string The SKU of the item to look up
header boolean (optional) Set to false to hide chart header for embedding (default: true) (optional)
height number (optional) Chart height in pixels (default: 500 with header, 400 without) (optional)
width string (optional) Chart width (default: 100%) (optional)
Response
HTML page with interactive chart

Example: /api/graph/40;11;kt-3?header=false&height=350

POST /api/items-bulk

Returns the latest price for each SKU in the provided array.

Parameters
Parameter Type Description
skus array Array of SKU strings to look up
Request Body
{
  "skus": [
    "40;11;kt-3",
    "202;11;australium"
  ]
}
Response
[
  {
    "name": "Strange Professional Killstreak Backburner",
    "sku": "40;11;kt-3",
    "source": "bptf",
    "time": 1748874425,
    "buy": {
      "keys": 4,
      "metal": 11.33
    },
    "sell": {
      "keys": 4,
      "metal": 69.22
    }
  }
]

Example: /api/items-bulk

GET /api/snapshot/:timestamp

Returns the latest price for each SKU as of the given unix timestamp.

Parameters
Parameter Type Description
timestamp number Unix timestamp (seconds)
Response
[
  {
    "name": "Strange Professional Killstreak Backburner",
    "sku": "40;11;kt-3",
    "source": "bptf",
    "time": 1748874425,
    "buy": {
      "keys": 4,
      "metal": 11.33
    },
    "sell": {
      "keys": 4,
      "metal": 69.22
    }
  }
]

Example: /api/snapshot/1700000000

GET /api/search

Fuzzy search for items by name. Returns up to 10 matching items ordered by relevance.

Parameters
Parameter Type Description
q string Search query (minimum 2 characters)
limit number Maximum results to return (default: 10, max: 50) (optional)
Response
{
  "query": "backburner",
  "results": [
    {
      "name": "Strange Professional Killstreak Backburner",
      "sku": "40;11;kt-3",
      "source": "bptf",
      "time": 1748874425,
      "buy": {
        "keys": 4,
        "metal": 11.33
      },
      "sell": {
        "keys": 4,
        "metal": 69.22
      },
      "relevance": 900
    }
  ],
  "total": 1,
  "limit": 5
}

Example: /api/search?q=backburner&limit=5

GET /api/compare/:sku1/:sku2

Compare two items side by side with price differences and history.

Parameters
Parameter Type Description
sku1 string SKU of the first item to compare
sku2 string SKU of the second item to compare
Response
{
  "items": {
    "40;11;kt-3": {
      "name": "Strange Professional Killstreak Backburner",
      "sku": "40;11;kt-3",
      "buy": {
        "keys": 4,
        "metal": 11.33
      },
      "sell": {
        "keys": 4,
        "metal": 69.22
      }
    },
    "202;11;australium": {
      "name": "Australium Rocket Launcher",
      "sku": "202;11;australium",
      "buy": {
        "keys": 45,
        "metal": 0
      },
      "sell": {
        "keys": 50,
        "metal": 0
      }
    }
  },
  "comparison": {
    "buyDifference": {
      "keys": -41,
      "metal": 11.33
    },
    "sellDifference": {
      "keys": -46,
      "metal": 69.22
    }
  },
  "history": {
    "40;11;kt-3": [],
    "202;11;australium": []
  },
  "meta": {
    "compared": "2025-01-01T00:00:00.000Z",
    "historyDays": 30
  }
}

Example: /api/compare/40;11;kt-3/202;11;australium

GET /api/cache-stats

Returns cache performance and system statistics.

Response
{
  "cache": {
    "size": 42,
    "maxSize": 1000,
    "activeTimers": 15
  },
  "database": {
    "totalPrices": 150000,
    "uniqueItems": 5000,
    "latestUpdate": 1748874425
  }
}

Example: /api/cache-stats

🤖 Bot Integration Endpoints

GET /api/autob/items

Returns full pricelist for TF2Autobot integration.

Example: /api/autob/items

GET /api/autob/items/:sku

Returns single item price for TF2Autobot integration.

Parameters
Parameter Type Description
sku string The SKU of the item to look up

Example: /api/autob/items/40;11;kt-3

POST /api/autob/items/:sku

Price check endpoint for TF2Autobot integration.

Parameters
Parameter Type Description
sku string The SKU of the item to check

Example: /api/autob/items/40;11;kt-3

🔌 WebSocket Integration

Connection Details
  • URL: ws://ws.pricedb.io/
  • Protocol: Socket.IO (not raw WebSocket)
  • Event: price - Emitted when prices update
Real-time Updates
  • Live price updates from BPTF Autopricer
  • Instant notifications for price changes
  • Compatible with TF2Autobot integration