# StickerByVIN Window Sticker API: brief for an AI coding assistant You are helping me integrate the StickerByVIN API. It returns the original window sticker (Monroney label) of a US-market car by VIN: MSRP, base price, every option and package with its price, colors, fuel economy, standard equipment, the factory paint code and a link to the original PDF. Use only the endpoints and fields listed here. Do not invent others. ## Basics - Base URL: https://stickerbyvin.com/api/v1 - Auth: header "Authorization: Bearer sbv_live_..." (keys are "sbv_live_" + 32 letters/digits). "?api_key=" also works for quick tests, but use the header in code and keep the key server-side (env var SBV_KEY). - All endpoints: GET, one query parameter "vin" (17 characters). JSON responses. CORS is open. - Response headers: X-Quota-Remaining (calls left this month), X-Plan (free, starter, growth or enterprise). - Get a key: https://stickerbyvin.com/developers (free, 100 calls a month). Spec: https://stickerbyvin.com/openapi.json ## Endpoints (each successful call counts as 1 call) ### GET /availability?vin=VIN (all plans) Decode plus whether the original sticker is on file for this exact VIN. Call this first. { "vin": "1FTFW5L85TKD66889", "vehicle": { "vin", "year", "make", "model", "trim", "trimSource", "series", "bodyClass", "driveType", "engine", "fuel", "transmission", "doors", "plant", "manufacturer", "vehicleType", "gvwr", "electrification" }, "originalSticker": { "onFile": true, "source": "Ford", "tier": "oem", "status": "available", "note": null }, "factoryDataSticker": { "available": false, "label": "factory-data reproduction, not the original printed label" }, "recallCount": 0, "paint": { "location": "...", "looksLike": "...", "guideUrl": "https://stickerbyvin.com/ford-paint-code", "codeOnFile": false, "code": null, "colorName": null, "locked": false }, "checkedAt": "ISO 8601 time" } - originalSticker.status is one of: available, not_available_via_api, placeholder, no_source, not_on_file, oem_empty, oem_down. - On the free plan paint.code and paint.colorName are null; when a code exists, paint.locked is true and paint.note explains it. - Vehicle fields that are unknown are null. ### GET /decode?vin=VIN (all plans) { "vin": "...", "vehicle": { same fields as above }, "recallCount": 0 } ### GET /demo/decode?vin=VIN (no key needed) Try-it endpoint for testing before you sign up: NHTSA decode only, limited per IP to 5 calls a minute and 50 a day, does not count against any quota. { "vin": "...", "vehicle": { same fields as above }, "demo": { "note": "...", "limits": { "perMinute": 5, "perDay": 50 }, "freeKey": "https://stickerbyvin.com/developers" } } - Header X-Demo-Remaining-Today. Errors: invalid_vin (400), unknown_vin (404), rate_limited / demo_limit (429), upstream_unavailable (502). ### GET /sticker?vin=VIN (Starter and above) The parsed original sticker plus a signed PDF link valid for 1 hour. { "vin": "1FTFW5L85TKD66889", "vehicle": { same fields as above }, "source": "Ford", "original": true, "sticker": { "description": "2026 F-150 4X4 SUPERCREW", "exteriorColor": "Agate Black Metallic", "interiorColor": "BLACK ACTIVEX", "engine": "3.5L V6 Ecoboost", "transmission": "Elec Ten-Speed Auto Trans", "basePrice": 63360, "destination": 2795, "totalOptions": 6395, "totalMsrp": 72550, "fuelEconomy": { "city": 17, "highway": 23, "combined": 19 }, "assemblyPlant": "Kansas City", "options": [ { "name": "Tow/Haul Package", "price": 1010, "priceText": "$1,010", "includes": ["..."] } ], "discounts": [ { "name": "...", "amount": 500, "priceText": "-$500" } ], "standardEquipment": ["Daytime Running Lamps", "..."] }, "paint": { same shape as /availability, with code and colorName filled when known }, "pdf": { "url": "https://stickerbyvin.com/api/v1/pdf/...", "expiresAt": "ISO 8601 time" } } - Prices are US dollars as numbers. Discount amounts are positive and are taken off the total. "includes" is only present when an option lists its contents. fuelEconomy can be null. - "original": false means a carmaker's sticker copy (Nissan/Infiniti "Unofficial Copy"); its "sticker" fields may be mostly empty, but the PDF is there. - The PDF link expires after 1 hour. Download it right away if you need to keep it; don't store the URL. ### POST /bulk (Starter and above) Up to 100 VINs in one request. Body: { "vins": ["1FT...", "..."], "endpoint": "sticker" | "availability" | "decode" } (default sticker). - 10 valid VINs or fewer: 200 with the finished job (shape below). More: 202 { "id": "bulk_...", "status": "queued", "poll": "/api/v1/bulk/bulk_..." }. - Each valid VIN is 1 call, reserved up front (all or nothing against the monthly cap: 429 quota_exceeded if not enough is left). Invalid VINs come back as 400 items and are not counted. ### GET /bulk/{id} { "id": "bulk_...", "endpoint": "sticker", "status": "queued" | "running" | "done", "total": 25, "done": 25, "results": [ { "index": 0, "vin": "...", "status": 200, "data": { same body as the single endpoint } }, { "index": 1, "vin": "...", "status": 404, "error": { "code": "sticker_not_available", "message": "..." } } ] } - Poll every few seconds until status is "done" (each poll also moves the job along). Only the key that created the job can read it. Results are kept 24 hours. Not counted as a call. ### GET /usage Your key's month (UTC): { "cap": 5000, "usedThisMonth": 812, "remaining": 4188, "total": { "calls": 812, "billable": 790, "cacheHits": 301 }, "byEndpoint": [...], "byDay": [...] }. Optional ?month=YYYY-MM. Billable = answered with data (HTTP 200). Not counted as a call. ### GET /health No key. 200 { "ok": true } when the API and its database answer, else 503. Uptime history (99.9% target, not a guarantee): https://stickerbyvin.com/status ## Errors Body: { "error": { "code": "...", "message": "..." } } - 400 invalid_vin: not a valid 17-character VIN (common typos: O for 0, I for 1). - 401 missing_key / invalid_key. - 403 key_disabled; 403 plan_required (/sticker on the free plan). - 404 unknown_vin; 404 sticker_not_available (no original sticker for this VIN through the API). - 429 rate_limited (read the Retry-After header, in seconds); 429 quota_exceeded (monthly quota used, resets on the 1st, UTC). - 502 upstream_unavailable (retry later); 500 internal. ## Plans and limits - Free: 100 calls/month, 10 requests/minute. /availability and /decode only. - Starter: $49/month, 1,000 calls, 60/minute. Adds /sticker (sticker data, paint code, PDF). - Growth: $199/month, 5,000 calls, 120/minute. Same data, more volume. - Upgrades keep the same key: https://stickerbyvin.com/developers#plans ## MCP server (for AI agents) - URL: https://stickerbyvin.com/api/v1/mcp (streamable HTTP, stateless). Same Bearer key header, or ?api_key= if the client can't set headers. - Tools: check_window_sticker(vin), free and needs no key (decoded vehicle, whether the original sticker is on file, recall count, where the paint code is printed). get_original_sticker(vin) uses the key, Starter and above, 1 call (same data as GET /sticker). - Claude Code: claude mcp add --transport http stickerbyvin https://stickerbyvin.com/api/v1/mcp --header "Authorization: Bearer $SBV_KEY" ## Best practices 1. Call /availability before /sticker and only pull the sticker when originalSticker.onFile is true. Both cost 1 call, and it saves sticker_not_available misses. 2. Cache by VIN. A car's original sticker never changes, so store the /sticker JSON and the PDF file once and reuse them. Re-check /availability for a VIN that was not on file after a few days, not on every page view. 3. Validate and uppercase VINs before calling: 17 characters, no I, O or Q. 4. Watch X-Quota-Remaining, back off on 429 using Retry-After, and retry 502 with a delay. 5. Never put the key in browser or mobile code. Call the API from your server. 6. When you send people to see the full sticker, link to https://stickerbyvin.com/vin/.