API Documentation

Overview

The TF2 Spell Handler API provides real-time endpoints for analysing spelled item premiums, calculating market trends, and accessing comprehensive spell data. All endpoints return JSON responses with CORS support for browser integration.

Base URL

https://spell.pricedb.io/api/spell

Rate Limiting

API requests are limited to100 requests per minute per IP address. Rate limit information is included in response headers:

• RateLimit-Limit- Maximum requests per window (100)
• RateLimit-Remaining- Remaining requests in current window
• RateLimit-Reset- Unix timestamp when the rate limit resets

Note:Health check endpoints (/health,/stats) and localhost requests are exempt from rate limiting.

Response Format

All responses are in JSON format with appropriate HTTP status codes:

• 200- Success
• 400- Bad Request (invalid or missing parameters)
• 404- Not Found (resource doesn't exist)
• 429- Rate Limit Exceeded (too many requests)
• 500- Internal Server Error

Price Format

All prices use standardized TF2 currency format:

{
  "total_ref": 115.1,        // Total value in refined metal
  "keys": 2,                 // Whole keys (at current rate: 57.55 ref/key)
  "metal": 0.0,              // Remaining refined metal
  "formatted": "2 keys"      // Human-readable format
}

Data Freshness

Data is collected and updated on the following schedule:

• Spell Listings:Every 6 hours (00:00, 06:00, 12:00, 18:00 UTC)
• Key Prices (Ref):Every 5 minutes from pricedb.io
• Key Prices (USD):Every 24 hours from Steam Community Market
• Analytics:Recalculated after each spell listing update

Spell Analytics Endpoints

These endpoints provide spell-specific analytics, premium calculations, and market insights based on real market data from Backpack.tf.

RECOMMENDED: Enhanced spell prediction with realistic flat-based price ranges. Combines market data with intelligent multipliers for low/mid/high estimates.

Parameters

Response

{
  "item_name": "Strange Rocket Launcher",
  "spells": [
    "Exorcism"
  ],
  "spell_ids": [
    2002
  ],
  "base_price": {
    "total_ref": 65.99,
    "keys": 1,
    "metal": 8.44,
    "formatted": "1 keys, 8.4 ref"
  },
  "predictions": {
    "low": {
      "total_ref": 1315.39,
      "keys": 22,
      "metal": 49.89,
      "formatted": "22 keys, 49.9 ref"
    },
    "mid": {
      "total_ref": 1731.75,
      "keys": 30,
      "metal": 6.25,
      "formatted": "30 keys, 6.3 ref"
    },
    "high": {
      "total_ref": 2356.61,
      "keys": 40,
      "metal": 56.11,
      "formatted": "40 keys, 56.1 ref"
    }
  },
  "premium_ranges": {
    "low": {
      "ref": 1249.4,
      "formatted": "21 keys, 41.4 ref"
    },
    "mid": {
      "ref": 1665.76,
      "formatted": "28 keys, 57.8 ref"
    },
    "high": {
      "ref": 2290.62,
      "formatted": "39 keys, 48.1 ref"
    }
  },
  "market_data": {
    "avg_flat_premium": 1665.76,
    "sample_size": 206,
    "confidence": "high"
  },
  "method": "flat_based_ranges",
  "key_rate": 57.55,
  "multipliers": {
    "low": 0.75,
    "mid": 1,
    "high": 1.35
  }
}

Example:/api/spell/predict?spells=Exorcism&item=Strange%20Rocket%20Launcher

Alternative prediction endpoint accepting POST body. Returns comprehensive spell premium predictions for specific items with market insights.

Parameters

Response

{
  "item_name": "Strange Scattergun",
  "base_price": {
    "total_ref": 115.1,
    "keys": 2,
    "metal": 0,
    "formatted": "2 keys"
  },
  "spell_premium": {
    "total_ref": 1249.4,
    "keys": 21,
    "metal": 41.45,
    "formatted": "21 keys, 41.4 ref"
  },
  "total_price": {
    "total_ref": 1364.5,
    "keys": 23,
    "metal": 41.45,
    "formatted": "23 keys, 41.4 ref"
  },
  "spell_data": {
    "spell_ids": [
      2003
    ],
    "spell_names": [
      "Pumpkin Bombs"
    ],
    "avg_flat_premium": 1249.4,
    "sample_size": 156,
    "confidence": "high"
  },
  "method": "flat_based",
  "key_rate": 57.55
}

Example:/api/spell/predict-spell-item

Calculate predicted premium for specific spell combinations based on market averages. Returns both flat (ref) and percentage-based premium estimates.

Parameters

Response

{
  "spell_ids": [
    2003,
    2002
  ],
  "predicted_flat": 25.5,
  "predicted_percent": 328.99,
  "avg_flat": 24.1,
  "avg_percent": 315.8,
  "count": 143,
  "confidence": "high"
}

Example:/api/spell/spell-value?ids=2003,2002

Get comprehensive market analytics for all spell combinations with sample sizes, averages, and update timestamps.

Response

[
  {
    "spell_combo": [
      2003
    ],
    "avg_flat": 1249.4,
    "avg_percent": 328.99,
    "count": 156,
    "last_updated": "2025-10-05T18:00:00.000Z"
  },
  {
    "spell_combo": [
      2002
    ],
    "avg_flat": 1665.76,
    "avg_percent": 531.26,
    "count": 206,
    "last_updated": "2025-10-05T18:00:00.000Z"
  }
]

Example:/api/spell/spell-analytics

Calculate detailed spell premium breakdown for a specific item and spell combination with base price, premium, and total.

Parameters

Response

{
  "item": "Strange Scattergun",
  "spell_ids": [
    2003
  ],
  "base_price": {
    "total_ref": 115.1,
    "keys": 2,
    "metal": 0,
    "formatted": "2 keys"
  },
  "spell_premium": {
    "total_ref": 1249.4,
    "keys": 21,
    "metal": 41.45,
    "formatted": "21 keys, 41.4 ref"
  },
  "total_price": {
    "total_ref": 1364.5,
    "keys": 23,
    "metal": 41.45,
    "formatted": "23 keys, 41.4 ref"
  },
  "premium_percent": 1085.6,
  "market_data": {
    "sample_size": 156,
    "confidence": "high",
    "avg_flat_premium": 1249.4
  }
}

Example:/api/spell/item-spell-premium?item=Strange%20Scattergun&ids=2003

Convert spell defindex ID to human-readable spell name.

Parameters

Response

{
  "id": 2003,
  "name": "Pumpkin Bombs",
  "type": "effect",
  "attributeId": 1004
}

Example:/api/spell/spell-id-to-name?id=2003

Convert spell name to defindex ID. Case-insensitive partial matching supported.

Parameters

Response

{
  "name": "Exorcism",
  "id": 2002,
  "type": "effect",
  "attributeId": 1003
}

Example:/api/spell/spell-name-to-id?name=Exorcism

Get complete list of all available TF2 spells with IDs, names, types, and attribute information.

Response

[
  {
    "id": 2003,
    "name": "Pumpkin Bombs",
    "type": "effect",
    "attributeId": 1004
  },
  {
    "id": 2002,
    "name": "Exorcism",
    "type": "effect",
    "attributeId": 1003
  },
  {
    "id": 2007,
    "name": "Team Spirit Footprints",
    "type": "footprint",
    "attributeId": 1008
  }
]

Example:/api/spell/spells

Data Collection Status

Monitor the spell data collection process and view collection statistics.

Get real-time status of the spell data collection service. Shows last run time, next scheduled collection, and comprehensive statistics including rate limits and errors.

Response

{
  "status": "active",
  "isRunning": false,
  "lastRunTime": "2025-10-05T18:00:00.000Z",
  "nextScheduledRun": "2025-10-06T00:00:00.000Z",
  "statistics": {
    "totalFetched": 1547,
    "totalAdded": 234,
    "totalUpdated": 56,
    "rateLimits": 2,
    "errors": 0
  },
  "schedule": "Every 6 hours (00:00, 06:00, 12:00, 18:00 UTC)",
  "historicalDataRange": "6 months (180 days)",
  "lastRunDuration": "24.5 minutes",
  "performance": {
    "itemsPerMinute": 63.1,
    "avgResponseTime": "952ms"
  }
}

Example:/api/spell/fetcher-status

Health & Service Monitoring

Endpoints for monitoring service health, retrieving system statistics, and checking operational status.

Simple health check endpoint for uptime monitoring and service availability checks. Returns 200 OK if service is operational.

Response

{
  "status": "ok",
  "timestamp": "2025-10-05T20:30:00.000Z",
  "uptime": "72h 15m",
  "version": "2.0.0"
}

Example:/api/spell/health

Comprehensive service statistics dashboard. Includes database health, spell fetcher status, cache metrics, and real-time system performance.

Response

{
  "status": "online",
  "timestamp": "2025-10-05T20:30:00.000Z",
  "database": {
    "connected": true,
    "totalSpelledItems": 1547,
    "analyzedCombos": 79,
    "lastCleanup": "2025-10-05T00:00:00.000Z"
  },
  "fetcher": {
    "status": "idle",
    "isRunning": false,
    "lastRun": "2025-10-05T18:00:00.000Z",
    "nextRun": "2025-10-06T00:00:00.000Z",
    "statistics": {
      "totalFetched": 1547,
      "totalAdded": 234,
      "totalUpdated": 56,
      "rateLimits": 2,
      "errors": 0
    }
  },
  "keyPrices": {
    "ref": 57.55,
    "usd": 2.14,
    "lastUpdated": {
      "ref": "2025-10-05T20:25:00.000Z",
      "usd": "2025-10-05T00:00:00.000Z"
    }
  },
  "performance": {
    "avgResponseTime": "45ms",
    "requestsPerMinute": 23,
    "cacheHitRate": "87%"
  },
  "spells": {
    "totalAvailable": 23,
    "withMarketData": 15,
    "avgPremium": "328.5%"
  }
}

Example:/api/stats

Proxy endpoint for accessing main pricedb.io status API. Returns unified status across all TF2 Price DB services.

Response

{
  "status": "operational",
  "services": {
    "api": "operational",
    "database": "operational",
    "spellHandler": "operational"
  },
  "lastUpdate": "2025-10-05T20:30:00.000Z"
}

Example:/api/spell/status-proxy

Understanding Predictions

Confidence Levels

Predictions include confidence levels based on available market data:

• High/Medium Confidence:Direct market data available for this specific item + spell combination. Predictions based on actual historical sales.
• Low Confidence:No direct data available - using predicted/estimated premiums based on similar spell combinations. Use with caution.

Price Ranges

Each prediction provides three price points:

• Low (0.75x):Conservative estimate for quick sales
• Mid (1.0x):Average market expectation
• High (1.35x):Optimistic estimate for patient sellers

Need Help?

For questions or issues, join ourDiscord communityor visitGitHub.