← Developers

API Documentation

Base URL: https://thrift.guide

Authentication

Free endpoints require no authentication. The ML pricing endpoint requires an API key, passed as a Bearer token or X-API-Key header. Get a key instantly at /developers.

Authorization: Bearer tg_your_key_here

Endpoints

GET/api/public/price

Get tier-based resale price estimate for a brand and category combination. Returns prices for all 5 condition grades. No authentication required.

Parameters

brandrequired— Brand slug (e.g. 'gucci', 'nike', 'hm')
categoryrequired— Category slug (e.g. 'bag', 'sneakers', 'jacket')
conditionoptional— Filter: 'New with tags', 'Like New', 'Good', 'Fair', 'Poor'

Example

curl "https://thrift.guide/api/public/price?brand=gucci&category=bag"
Response
{
  "brand": { "name": "Gucci", "slug": "gucci", "tier": "luxury", "tierLabel": "Luxury" },
  "category": { "name": "Bag", "slug": "bag" },
  "currency": "USD",
  "prices": [
    { "condition": "New with tags", "low": 520, "mid": 1170, "high": 2340 },
    { "condition": "Like New", "low": 440, "mid": 990, "high": 1980 },
    { "condition": "Good", "low": 400, "mid": 900, "high": 1800 },
    { "condition": "Fair", "low": 280, "mid": 630, "high": 1260 },
    { "condition": "Poor", "low": 160, "mid": 360, "high": 720 }
  ]
}
GET/api/public/ml-priceAPI key required

ML-powered price prediction from Circular's model, trained on millions of real resale transactions. Returns both an ML prediction with confidence score and a static tier-based estimate.

Parameters

brandrequired— Brand slug
categoryrequired— Category slug
conditionoptional— Condition filter for static estimate
genderoptional— 'male' or 'female' (default: female)

Example

curl -H "Authorization: Bearer tg_abc123..." \
  "https://thrift.guide/api/public/ml-price?brand=gucci&category=bag"
Response
{
  "brand": { "name": "Gucci", "slug": "gucci", "tier": "luxury" },
  "category": { "name": "Bag", "slug": "bag" },
  "currency": "USD",
  "source": "circular-ml",
  "mlPrediction": {
    "price": 274,
    "priceLow": 192,
    "priceHigh": 356,
    "confidence": 0.57,
    "note": "ML prediction from Circular"
  },
  "staticEstimate": {
    "prices": [{ "condition": "Good", "low": 400, "mid": 900, "high": 1800 }]
  },
  "poweredBy": "Circular (circular-resale.com)"
}
GET/api/public/brands

List all 55 supported brands grouped by tier (designer, luxury, premium, mid-range, fast-fashion).

Example

curl "https://thrift.guide/api/public/brands"
Response
{
  "total": 55,
  "tiers": [
    {
      "tier": "designer",
      "label": "Designer",
      "brands": [
        { "name": "Chanel", "slug": "chanel" },
        { "name": "Hermès", "slug": "hermes" },
        ...
      ]
    },
    ...
  ]
}
GET/api/public/categories

List all 15 supported clothing categories with their price modifiers.

Example

curl "https://thrift.guide/api/public/categories"
Response
{
  "total": 15,
  "categories": [
    { "name": "Bag", "slug": "bag", "priceModifier": 2.0 },
    { "name": "Coat", "slug": "coat", "priceModifier": 1.8 },
    { "name": "Jacket", "slug": "jacket", "priceModifier": 1.5 },
    ...
  ]
}
POST/api/public/keys

Generate a free API key instantly. Same email always returns the same key.

Parameters

emailrequired— Your email address (JSON body)

Example

curl -X POST https://thrift.guide/api/public/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'
Response
{
  "apiKey": "tg_a1b2c3d4e5f6...",
  "email": "you@example.com",
  "tier": "free",
  "limits": { "requestsPerDay": 100 }
}

Rate Limits

EndpointLimitCache
/api/public/priceUnlimited24h CDN
/api/public/brandsUnlimited24h CDN
/api/public/categoriesUnlimited24h CDN
/api/public/ml-price100/day per key1h private
MCP (/mcp)50 ML calls/day per IP—

Markdown Format

Append .md to any page URL to get a markdown version. Useful for AI agents and programmatic access.

curl https://thrift.guide/price/gucci/bag.md
curl https://thrift.guide/developers.md
curl https://thrift.guide/price.md
OpenAPI Specllms.txtFull ReferenceGet API Key