Spells API — docs.pricedb.io

General Information

Base URL:https://spell.pricedb.io

Real-time endpoints for analysing spelled item premiums, calculating market trends, and accessing comprehensive TF2 spell data. Market data is sourced from Backpack.tf listings.

Authentication:No authentication required.

Analytics

GET/api/spell/predictPredict spelled item price (enhanced)

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

**Confidence levels:**
- **High/Medium** — Direct market data for this item + spell combination
- **Low** — No direct data; estimated from similar spell combinations

Parameters

Name	In	Type	Description
spells	query	string	Comma-separated spell names
item	query	string	Item name for price prediction

Response

Spell price prediction with low/mid/high ranges

{
  "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
  }
}

Try in browser

POST/api/spell/predict-spell-itemPredict spelled item price (POST)

Alternative prediction endpoint accepting a JSON body. Returns comprehensive spell premium predictions for a specific item with market insights.

Request Body

{
  "item_name": "Strange Scattergun",
  "spell_ids": [
    2003
  ]
}

Response

Spell premium prediction for the given item

{
  "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
}

GET/api/spell/spell-valueGet predicted premium for a spell combination

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

Parameters

Name	In	Type	Description
ids	query	string	Comma-separated spell defindex IDs

Response

Spell premium values

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

Try in browser

GET/api/spell/spell-analyticsGet all spell combination analytics

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

Response

Array of spell combination analytics

[
  {
    "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"
  }
]

Try in browser

GET/api/spell/item-spell-premiumGet spell premium breakdown for an item

Calculates detailed spell premium breakdown for a specific item and spell combination, including base price, premium, and total.

Parameters

Name	In	Type	Description
item	query	string	Item name or SKU
ids	query	string	Comma-separated spell defindex IDs

Response

Item spell premium breakdown

{
  "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
  }
}

Try in browser

Spells

GET/api/spell/spell-id-to-nameConvert spell ID to name

Returns the human-readable spell name and metadata for a given spell defindex ID.

Parameters

Name	In	Type	Description
id	query	integer	Spell defindex ID

Response

Spell metadata

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

Try in browser

GET/api/spell/spell-name-to-idConvert spell name to ID

Returns the defindex ID and metadata for a given spell name. Case-insensitive partial matching is supported.

Parameters

Name	In	Type	Description
name	query	string	Spell name (case-insensitive)

Response

Spell metadata

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

Try in browser

GET/api/spell/spellsList all spells

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

Response

Array of all spell definitions

[
  {
    "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
  }
]

Try in browser

Data Collection

GET/api/spell/fetcher-statusGet data collection status

Returns real-time status of the spell data collection service, including last run time, next scheduled collection, and comprehensive statistics.

Response

Fetcher status and statistics

{
  "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"
  }
}

Try in browser

Health

GET/api/spell/healthHealth check

Simple health check endpoint for uptime monitoring. Returns `200 OK` if the service is operational. Exempt from rate limiting.

Response

Service is operational

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

Try in browser

GET/api/statsService statistics dashboard

Comprehensive statistics including database health, spell fetcher status, cache metrics, and real-time system performance. Exempt from rate limiting.

Response

Full service statistics

{
  "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%"
  }
}

Try in browser

GET/api/spell/status-proxyStatus proxy

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

Response

Unified service status

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

Try in browser