API Reference

REST API Reference

Bindarr provides a clean RESTful API for reading collection metrics, pulling inventory data, or integrating with external finance dashboards, Home Assistant widgets, and custom scripts.

---

Authentication

All API requests (except /api/health and /api/shared/:token) require authentication via an HTTP Authorization header:

Authorization: Bearer <YOUR_API_KEY_OR_SESSION_TOKEN>

Read-Only External API Keys

For external scripts and dashboards, generate a dedicated read-only API key under Settings → API Keys.

• Security Constraint: External API keys are permanently restricted to HTTP GET requests only. Any POST, PUT, or DELETE attempt will return 403 Forbidden.
• Admin Isolation: External keys cannot access administrative routes (/api/admin/*).

---

Core Endpoints

1. System Health Check

GET /api/health

Unauthenticated health probe used by container orchestrators and Docker health checks.

Example Response:

{
  "status": "ok"
}

---

2. Collection Net Worth

GET /api/stats/networth
GET /api/stats/networth?game=pokemon
GET /api/stats/networth?game=mtg

Returns summarized portfolio value, total cards, acquisition cost, and financial gain/loss metrics.

Example Request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:3001/api/stats/networth

Example Response:

{
  "totalValue": 4210.55,
  "totalSpent": 2980.00,
  "gain": 1230.55,
  "gainPct": 41.3,
  "totalCards": 812,
  "uniqueEntries": 604,
  "byGame": {
    "pokemon": {
      "cards": 500,
      "value": 3100.20
    },
    "mtg": {
      "cards": 312,
      "value": 1110.35
    }
  },
  "currencies": ["USD"],
  "asOf": "2026-08-20T17:00:00.000Z"
}

---

3. Comprehensive Dashboard Statistics

GET /api/stats

Returns full collection analytics including rarity distributions, card type breakdowns, and set completion percentages.

Example Response:

{
  "totalCards": 812,
  "totalValue": 4210.55,
  "rarityBreakdown": [
    { "rarity": "Illustration Rare", "count": 45 },
    { "rarity": "Special Illustration Rare", "count": 12 },
    { "rarity": "Mythic", "count": 28 }
  ],
  "typeBreakdown": [
    { "type": "Pokémon", "count": 380 },
    { "type": "Trainer", "count": 120 },
    { "type": "Creature", "count": 190 },
    { "type": "Instant", "count": 60 }
  ]
}

---

4. Fetch Collection Inventory

GET /api/collection
GET /api/collection?game=pokemon&location_id=1

Returns your card inventory including physical storage locations, condition, printing, and market valuation.

Example Response:

[
  {
    "id": 104,
    "card_id": "sv1-198",
    "name": "Gardevoir ex",
    "printed_name": "Gardevoir ex",
    "set_id": "sv1",
    "set_name": "Scarlet & Violet",
    "number": "198",
    "rarity": "Special Illustration Rare",
    "language": "English",
    "condition": "Near Mint",
    "printing": "Holofoil",
    "quantity": 1,
    "market_value": null,
    "price_normal": null,
    "price_holofoil": 38.50,
    "price_currency": "USD",
    "location_name": "Binder 1",
    "compartment_label": "Page 4",
    "position": 2000,
    "grader": "PSA",
    "grade": 10,
    "cert_number": "12345678"
  }
]

---

5. Card Price History

GET /api/cards/:id/price-history

Returns historical price data points for a specific card over 7-day, 30-day, and 90-day windows.

Example Response:

[
  { "date": "2026-08-01", "price": 32.00 },
  { "date": "2026-08-10", "price": 35.50 },
  { "date": "2026-08-20", "price": 38.50 }
]

---

6. Public Shared Collection

GET /api/shared/:share_token

Public unauthenticated read-only endpoint returning public collection cards for an enabled share token.

---

HTTP Status Codes

Status Code	Meaning
200 OK	Request succeeded.
400 Bad Request	Invalid query parameters or body format.
401 Unauthorized	Missing or expired Bearer session token.
403 Forbidden	Read-only API key attempted a non-GET operation or accessed an admin route.
404 Not Found	Requested card, location, deck, or user does not exist.
429 Too Many Requests	Rate limit exceeded.
503 Service Unavailable	Scanning attempted before ONNX models or catalogs were initialized (notBuilt).