{ "openapi": "3.1.0", "info": { "title": "CarScout API", "version": "1.0.0", "summary": "Used-car market snapshots, NHTSA recalls, and VIN decoding.", "description": "Public GET endpoints for market snapshots and VIN decoding need no key, 30 requests a minute for each IP address. The MCP server is described as one JSON-RPC endpoint. Docs: https://usecarscout.com/docs", "contact": { "name": "CarScout", "url": "https://usecarscout.com" } }, "externalDocs": { "description": "CarScout developer docs", "url": "https://usecarscout.com/docs" }, "servers": [ { "url": "https://api.usecarscout.com/api/v1" } ], "tags": [ { "name": "Market", "description": "Market snapshots for each model year." }, { "name": "VIN", "description": "VIN decoding." }, { "name": "MCP", "description": "The MCP server for AI assistants." } ], "paths": { "/market/models": { "get": { "tags": [ "Market" ], "operationId": "listModels", "summary": "List tracked models", "description": "Every tracked model with its latest snapshot, plus totals for each make.", "responses": { "200": { "description": "The models.", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed each minute.", "schema": { "type": "integer", "example": 30 } }, "X-RateLimit-Remaining": { "description": "Requests left in this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the window resets, as Unix time in seconds.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "models": { "type": "array", "items": { "$ref": "#/components/schemas/ModelSummary" } }, "makeStats": { "type": "object", "additionalProperties": { "type": "object" } }, "stats": { "type": "object", "properties": { "totalModels": { "type": "integer" }, "totalMakes": { "type": "integer" }, "totalListings": { "type": "integer" }, "currentSnapshotDate": { "type": "string", "format": "date" } } } } } } } } } }, "429": { "description": "Too many requests from this IP address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Rate limit exceeded. Please try again later.", "code": "RATE_LIMIT_EXCEEDED" } } } } } } }, "/market/models/{makeSlug}/{modelSlug}": { "get": { "tags": [ "Market" ], "operationId": "getModel", "summary": "Get a model and its years", "parameters": [ { "name": "makeSlug", "in": "path", "required": true, "description": "The make in lowercase with hyphens.", "schema": { "type": "string", "example": "toyota" } }, { "name": "modelSlug", "in": "path", "required": true, "description": "The model in lowercase with hyphens.", "schema": { "type": "string", "example": "rav4" } } ], "responses": { "200": { "description": "The model and each model year with its latest snapshot.", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed each minute.", "schema": { "type": "integer", "example": 30 } }, "X-RateLimit-Remaining": { "description": "Requests left in this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the window resets, as Unix time in seconds.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "model": { "$ref": "#/components/schemas/Model" }, "years": { "type": "array", "items": { "type": "object" } } } } } } } } }, "404": { "description": "No tracked model or model year matches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Model not found", "code": "NOT_FOUND" } } } }, "429": { "description": "Too many requests from this IP address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Rate limit exceeded. Please try again later.", "code": "RATE_LIMIT_EXCEEDED" } } } } } } }, "/market/models/{makeSlug}/{modelSlug}/{year}": { "get": { "tags": [ "Market" ], "operationId": "getModelYear", "summary": "Get a model year snapshot", "description": "The latest snapshot, with recalls, complaints, and fuel economy. Snapshots have no median price, and mileage is accurate only to a 50,000-mile band.", "parameters": [ { "name": "makeSlug", "in": "path", "required": true, "description": "The make in lowercase with hyphens.", "schema": { "type": "string", "example": "toyota" } }, { "name": "modelSlug", "in": "path", "required": true, "description": "The model in lowercase with hyphens.", "schema": { "type": "string", "example": "rav4" } }, { "name": "year", "in": "path", "required": true, "description": "The model year.", "schema": { "type": "integer", "example": 2021 } } ], "responses": { "200": { "description": "The model year.", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed each minute.", "schema": { "type": "integer", "example": 30 } }, "X-RateLimit-Remaining": { "description": "Requests left in this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the window resets, as Unix time in seconds.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "model": { "$ref": "#/components/schemas/Model" }, "modelYear": { "type": "object" }, "snapshot": { "$ref": "#/components/schemas/Snapshot" } }, "additionalProperties": true } } } } } }, "404": { "description": "No tracked model or model year matches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Model not found", "code": "NOT_FOUND" } } } }, "429": { "description": "Too many requests from this IP address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Rate limit exceeded. Please try again later.", "code": "RATE_LIMIT_EXCEEDED" } } } } } } }, "/market/models/{makeSlug}/{modelSlug}/{year}/history": { "get": { "tags": [ "Market" ], "operationId": "getModelYearHistory", "summary": "Get earlier snapshots for a model year", "parameters": [ { "name": "makeSlug", "in": "path", "required": true, "description": "The make in lowercase with hyphens.", "schema": { "type": "string", "example": "toyota" } }, { "name": "modelSlug", "in": "path", "required": true, "description": "The model in lowercase with hyphens.", "schema": { "type": "string", "example": "rav4" } }, { "name": "year", "in": "path", "required": true, "description": "The model year.", "schema": { "type": "integer", "example": 2021 } } ], "responses": { "200": { "description": "The snapshots, newest first.", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed each minute.", "schema": { "type": "integer", "example": 30 } }, "X-RateLimit-Remaining": { "description": "Requests left in this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the window resets, as Unix time in seconds.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "type": "object", "properties": { "makeSlug": { "type": "string" }, "modelSlug": { "type": "string" }, "year": { "type": "integer" }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/Snapshot" } } } } } } } } }, "404": { "description": "No tracked model or model year matches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Model not found", "code": "NOT_FOUND" } } } }, "429": { "description": "Too many requests from this IP address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Rate limit exceeded. Please try again later.", "code": "RATE_LIMIT_EXCEEDED" } } } } } } }, "/vehicle-data/decode-vin/{vin}": { "get": { "tags": [ "VIN" ], "operationId": "decodeVin", "summary": "Decode a VIN", "description": "Decodes a VIN with NHTSA vPIC. Partial VINs of 8 to 16 characters decode what they can.", "parameters": [ { "name": "vin", "in": "path", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 17, "example": "1HGCV1F30LA012345" } } ], "responses": { "200": { "description": "The decoded vehicle.", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed each minute.", "schema": { "type": "integer", "example": 30 } }, "X-RateLimit-Remaining": { "description": "Requests left in this minute.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "When the window resets, as Unix time in seconds.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "data" ], "properties": { "success": { "const": true }, "data": { "$ref": "#/components/schemas/DecodedVin" } } } } } }, "400": { "description": "The VIN has the wrong length or characters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Invalid VIN format", "code": "INVALID_VIN" } } } }, "429": { "description": "Too many requests from this IP address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "error": "Rate limit exceeded. Please try again later.", "code": "RATE_LIMIT_EXCEEDED" } } } } } } }, "/mcp": { "servers": [ { "url": "https://mcp.usecarscout.com" } ], "post": { "tags": [ "MCP" ], "operationId": "mcpRequest", "summary": "Send one MCP JSON-RPC message", "description": "Public tools need no credentials: get_market_data, check_recalls, decode_vin. Account tools need OAuth or an API key: create_scout, list_scouts, get_scout, update_scout, delete_scout, check_limits, get_alerts, dismiss_alert, submit_feedback.", "security": [ {}, { "carscoutOAuth": [] }, { "apiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JsonRpcRequest" }, "examples": { "get_market_data": { "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_market_data", "arguments": { "make": "Toyota", "model": "RAV4", "year": 2021 } } } }, "check_recalls": { "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "check_recalls", "arguments": { "make": "Ford", "model": "Explorer", "year": 2020 } } } }, "decode_vin": { "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "decode_vin", "arguments": { "vin": "1HGCV1F30LA012345" } } } }, "check_limits": { "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "check_limits", "arguments": {} } } }, "create_scout": { "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "create_scout", "arguments": { "requestId": "CREATION_REQUEST_ID", "make": "Toyota", "model": "RAV4", "trims": [ "XLE" ], "yearMin": 2020, "yearMax": 2024, "priceMax": 28000, "zipCode": "11201", "maxDistanceMiles": 100 } } } }, "list_scouts": { "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "list_scouts", "arguments": {} } } }, "get_scout": { "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_scout", "arguments": { "id": "SCOUT_ID" } } } }, "update_scout": { "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "update_scout", "arguments": { "id": "SCOUT_ID", "priceMax": 32000 } } } }, "delete_scout": { "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "delete_scout", "arguments": { "id": "SCOUT_ID" } } } }, "get_alerts": { "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_alerts", "arguments": { "scoutId": "SCOUT_ID", "limit": 10 } } } }, "dismiss_alert": { "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "dismiss_alert", "arguments": { "alertId": "ALERT_ID", "reason": "not_interested" } } } }, "submit_feedback": { "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "submit_feedback", "arguments": { "type": "bug", "title": "TITLE", "description": "DESCRIPTION" } } } } } } } }, "responses": { "200": { "description": "The JSON-RPC response, as JSON or a server-sent event." }, "401": { "description": "An account tool was called without valid credentials. The WWW-Authenticate header points to the OAuth metadata." }, "403": { "description": "The token lacks the scope this tool needs (insufficient_scope)." } } } } }, "components": { "securitySchemes": { "carscoutOAuth": { "type": "oauth2", "description": "OAuth 2.0 authorization code flow with PKCE, for the MCP account tools.", "flows": { "authorizationCode": { "authorizationUrl": "https://clerk.usecarscout.com/oauth/authorize", "tokenUrl": "https://clerk.usecarscout.com/oauth/token", "scopes": { "carscout:read": "Read your scouts, alerts, and limits.", "carscout:write": "Create, change, and delete scouts, dismiss alerts, and send feedback." } } } }, "apiKey": { "type": "http", "scheme": "bearer", "description": "A CarScout API key from Settings > Account, for the MCP account tools." } }, "schemas": { "Error": { "type": "object", "required": [ "success", "error" ], "properties": { "success": { "const": false }, "error": { "type": "string" }, "code": { "type": "string" } } }, "Model": { "type": "object", "properties": { "make": { "type": "string" }, "model": { "type": "string" }, "makeSlug": { "type": "string" }, "modelSlug": { "type": "string" } }, "additionalProperties": true }, "ModelSummary": { "type": "object", "properties": { "make": { "type": "string" }, "model": { "type": "string" }, "makeSlug": { "type": "string" }, "modelSlug": { "type": "string" }, "yearCount": { "type": "integer" }, "latestSnapshot": { "type": [ "object", "null" ], "properties": { "snapshotDate": { "type": "string", "format": "date" }, "listingCount": { "type": "integer" } } } } }, "Snapshot": { "type": "object", "properties": { "snapshotDate": { "type": "string", "format": "date" }, "listingCount": { "type": "integer" }, "medianPrice": { "type": "null", "description": "Always null: snapshots have no median price." }, "meanPrice": { "type": [ "integer", "null" ], "description": "Average asking price for the model year, in US dollars." }, "meanMileage": { "type": [ "integer", "null" ], "description": "Interpolated from 50,000-mile bands; accurate only to the band." }, "medianMileage": { "type": [ "integer", "null" ], "description": "Interpolated from 50,000-mile bands; accurate only to the band. Recent model years come out at 25,000 regardless of the cars." }, "mileagePercentiles": { "type": [ "object", "null" ], "description": "p25, p50, and p75 are interpolated from 50,000-mile bands and accurate only to the band. under50k, under100k, under150k, and under200k are exact shares of listings below each band edge, present on snapshots collected from late October 2026.", "properties": { "p25": { "type": "integer" }, "p50": { "type": "integer" }, "p75": { "type": "integer" }, "under50k": { "type": "number" }, "under100k": { "type": "number" }, "under150k": { "type": "number" }, "under200k": { "type": "number" } } }, "stateCounts": { "type": [ "object", "null" ], "additionalProperties": { "type": "integer" } } }, "additionalProperties": true }, "DecodedVin": { "type": "object", "properties": { "vin": { "type": "string" }, "make": { "type": "string" }, "model": { "type": "string" }, "year": { "type": "string" }, "body_style": { "type": "string" }, "transmission": { "type": "string" }, "drivetrain": { "type": "string" }, "fuel_type": { "type": "string" }, "engine": { "type": "string" }, "plant": { "type": "string" }, "vehicle_type": { "type": "string" }, "valid": { "type": "boolean", "description": "False when the check digit fails. The other fields still hold what was decoded." }, "partial": { "type": "boolean" } } }, "JsonRpcRequest": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer" ] }, "method": { "type": "string", "enum": [ "initialize", "notifications/initialized", "tools/list", "tools/call", "prompts/list", "prompts/get", "resources/list", "resources/read", "ping" ] }, "params": { "type": "object" } } } } } }