DealScore
Docs

API reference

Programmatic access to the same scoring engine as the homepage form. REST for simple calls; MCP Streamable HTTP for agent tool use.

For agents

DealScore is a remote MCP server plus a small REST API. Discovery files are public JSON (no auth, no secrets):

Cursor-style MCP config (OAuth — preferred):

{
  "mcpServers": {
    "dealscore": {
      "url": "https://cardealscore.com/api/mcp"
    }
  }
}

API key config remains for curl, scripts, and clients that cannot do OAuth:

{
  "mcpServers": {
    "dealscore": {
      "url": "https://cardealscore.com/api/mcp",
      "headers": { "x-api-key": "YOUR_KEY" }
    }
  }
}

REST endpoints:

  • POST /api/score — grade a deal
  • POST /api/explain — map delta_pct to a grade
  • GET /api/health — service health (no auth)

Auth for REST (and MCP clients that still use keys):

  • x-api-key: YOUR_KEY
  • Authorization: Bearer YOUR_KEY

Sign in to create an API key. Get a key.

Usage meter

Live scores share one Free meter per signed-in user: 40 deals per UTC month that return coverage: scored. Homepage, REST, and MCP increment the same counter. cannot_score and validation errors do not count. Over the cap, POST /api/score and POST /api/internal/score return 402 with an upgrade payload. MCP score_deal returns a tool error. There is no silent mock.

Get a key

Sign in with an email magic link, then create or revoke keys on /keys. The homepage web form uses the same signed-in Free meter as these keys. Operator env keys (DEALSCORE_API_KEYS) remain as break-glass.

Sign in to create an API key (email magic link). Create and revoke keys on /keys. Live scores share a Free meter of 40 scored deals per month. Sign in on the homepage before live scoring.

Base URL

Production: https://cardealscore.com. Local dev: http://localhost:3000.

Authentication

MCP clients should use OAuth (add /api/mcp, sign in in the browser). See /auth. POST /api/score and POST /api/explain use API keys. Send either:

  • x-api-key: YOUR_KEY
  • Authorization: Bearer YOUR_KEY

GET /api/health is open. In local dev with no keys configured, programmatic routes work without auth.

Sign in to create an API key (email magic link). Create and revoke keys on /keys. Live scores share a Free meter of 40 scored deals per month. Sign in on the homepage before live scoring.

Endpoints

GET /api/health
No auth. Env and mode check.
curl -sS https://cardealscore.com/api/health
POST /api/score
Score a deal. YMM or VIN + price + mileage. ZIP is optional.
curl -X POST https://cardealscore.com/api/score \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{
    "year": 2020,
    "make": "Toyota",
    "model": "Camry",
    "asking_price": 18500,
    "mileage": 62000,
    "zip": "33803"
  }'
POST /api/explain
Map a delta_pct to grade without scoring.
curl -X POST https://cardealscore.com/api/explain \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{ "delta_pct": -0.08 }'
POST /api/mcp
MCP Streamable HTTP. OAuth for agents; API keys still work. Tools: score_deal, explain_grade, health.
{
  "mcpServers": {
    "dealscore": {
      "url": "https://cardealscore.com/api/mcp"
    }
  }
}

Response fields (score)

Key fields in a successful score:

  • grade, score, delta_pct — score_v1 rubric
  • expected_price, expected_price_low/high — expected market value band from comps
  • comps_count, data_source (live | mock | error), coverage (scored | cannot_score | partial)
  • brief, risks, confidence

More

Agent-oriented summary: llms.txt. OAuth discovery: /.well-known/oauth-protected-resource. MCP discovery: /.well-known/mcp/server-card.json. Guides: VIN scoring, judging a deal, scoring with an agent.