# API reference

Programmatic access to the same DealScore engine as the [homepage form](https://cardealscore.com/). REST for simple calls; MCP Streamable HTTP for agent tool use.

- HTML: https://cardealscore.com/docs/api
- Markdown: https://cardealscore.com/docs/api.md
- Auth: https://cardealscore.com/auth.md

## For agents

Discovery files are public JSON (no auth, no secrets):

- MCP: https://cardealscore.com/api/mcp
- Server card: https://cardealscore.com/.well-known/mcp/server-card.json
- OAuth resource metadata: https://cardealscore.com/.well-known/oauth-protected-resource
- OAuth authorization server: https://cardealscore.com/.well-known/oauth-authorization-server
- API catalog: https://cardealscore.com/.well-known/api-catalog
- Agent skills: https://cardealscore.com/.well-known/agent-skills/index.json
- llms.txt: https://cardealscore.com/llms.txt
- Health: `GET https://cardealscore.com/api/health` (no auth)

Cursor-style MCP config (OAuth — preferred):

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

API key config (curl / scripts / clients without OAuth):

```json
{
  "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 headers for REST and for MCP clients that still use keys:

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

MCP OAuth clients send `Authorization: Bearer <access_token>` after browser consent. Sign in to create an API key. See https://cardealscore.com/docs/api#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 is `402` (REST) or a tool error (MCP). Never a silent mock.

## Get a key

[Sign in to create an API key](https://cardealscore.com/login). Email magic link — no password. Manage keys at https://cardealscore.com/keys. Live scores share a Free meter of 40 scored deals per month. Sign in on the homepage before live scoring. Details: https://cardealscore.com/docs/api#get-a-key

## Example

```bash
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"
  }'
```