{
 "openapi": "3.1.0",
 "info": {
  "title": "StickerByVIN Window Sticker API",
  "version": "1.0.0",
  "summary": "The original Monroney window sticker by VIN as JSON, plus VIN decode and sticker availability.",
  "description": "Returns the original window sticker (Monroney label) the carmaker printed, as JSON: MSRP, base price, destination, every option and package with its price, colours, fuel economy, standard equipment, the factory paint code and a signed link to the original PDF. Also VIN decode and a check of whether the original sticker is on file.\n\nCoverage: Ford and Lincoln; GM (Chevrolet, GMC, Buick, Cadillac) 2022+; most Jeep, Ram, Dodge, Chrysler 2017+; Subaru 2021+. Call /availability first.\n\nPlans: Free $0 (50 calls/month, availability + decode), Starter $49/month (1,000 calls, sticker data + PDF), Growth $199/month (5,000 calls), Enterprise on request. Free key in 30 seconds: https://stickerbyvin.com/developers\n\nMCP server for AI agents: https://stickerbyvin.com/api/v1/mcp (tools check_window_sticker, get_original_sticker).",
  "contact": {
   "name": "StickerByVIN",
   "email": "support@stickerbyvin.com",
   "url": "https://stickerbyvin.com/developers"
  },
  "termsOfService": "https://stickerbyvin.com/terms",
  "x-logo": {
   "url": "https://stickerbyvin.com/icon-512.png"
  }
 },
 "externalDocs": {
  "description": "Docs and free key",
  "url": "https://stickerbyvin.com/developers"
 },
 "servers": [
  {
   "url": "https://stickerbyvin.com/api/v1"
  }
 ],
 "security": [
  {
   "bearerAuth": []
  }
 ],
 "tags": [
  {
   "name": "Window sticker"
  },
  {
   "name": "VIN decode"
  }
 ],
 "paths": {
  "/availability": {
   "get": {
    "operationId": "getAvailability",
    "tags": [
     "Window sticker"
    ],
    "summary": "Check whether the original window sticker is on file for a VIN",
    "description": "Decode plus whether the original sticker is on file, its source, the model's recall count and where the paint code is printed (the exact paint code on paid plans). All plans. 1 call.",
    "parameters": [
     {
      "name": "vin",
      "in": "query",
      "required": true,
      "description": "The 17-character VIN",
      "schema": {
       "type": "string",
       "minLength": 17,
       "maxLength": 17
      },
      "example": "1FTFW5L85TKD66889"
     }
    ],
    "responses": {
     "200": {
      "description": "Availability",
      "headers": {
       "X-Quota-Remaining": {
        "schema": {
         "type": "integer"
        },
        "description": "Calls left this month"
       },
       "X-Plan": {
        "schema": {
         "type": "string"
        },
        "description": "The key's plan"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Availability"
        },
        "example": {
         "vin": "1FTFW5L85TKD66889",
         "vehicle": {
          "vin": "1FTFW5L85TKD66889",
          "year": 2026,
          "make": "FORD",
          "model": "F-150",
          "trim": "Lariat"
         },
         "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": "the Safety Compliance Certification label on the driver door jamb (B-pillar)",
          "looksLike": "a 2-character code next to \"EXT PNT\", e.g. UM",
          "guideUrl": "https://stickerbyvin.com/ford-paint-code",
          "codeOnFile": false,
          "code": null,
          "colorName": null,
          "locked": true,
          "note": "The exact paint code and color name are returned on paid plans (Starter and above)."
         },
         "checkedAt": "2026-11-17T10:00:00.000Z"
        }
       }
      }
     },
     "400": {
      "description": "Invalid VIN",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid key",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "Key disabled, or the endpoint needs a paid plan",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "404": {
      "description": "Unknown VIN, or no original sticker available",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Rate limited or monthly quota used",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "502": {
      "description": "Upstream VIN database unavailable",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/decode": {
   "get": {
    "operationId": "decodeVin",
    "tags": [
     "VIN decode"
    ],
    "summary": "Decode a VIN",
    "description": "Year, make, model, trim, engine, drivetrain, body, assembly plant (NHTSA-based, trim refined from the sticker when on file). All plans. 1 call.",
    "parameters": [
     {
      "name": "vin",
      "in": "query",
      "required": true,
      "description": "The 17-character VIN",
      "schema": {
       "type": "string",
       "minLength": 17,
       "maxLength": 17
      },
      "example": "1FTFW5L85TKD66889"
     }
    ],
    "responses": {
     "200": {
      "description": "Decoded vehicle",
      "headers": {
       "X-Quota-Remaining": {
        "schema": {
         "type": "integer"
        },
        "description": "Calls left this month"
       },
       "X-Plan": {
        "schema": {
         "type": "string"
        },
        "description": "The key's plan"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Decode"
        }
       }
      }
     },
     "400": {
      "description": "Invalid VIN",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid key",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "Key disabled, or the endpoint needs a paid plan",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "404": {
      "description": "Unknown VIN, or no original sticker available",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Rate limited or monthly quota used",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "502": {
      "description": "Upstream VIN database unavailable",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/sticker": {
   "get": {
    "operationId": "getSticker",
    "tags": [
     "Window sticker"
    ],
    "summary": "Get the original window sticker as JSON, plus the PDF",
    "description": "The parsed original Monroney label with every option and price, the matched factory paint code and a signed PDF link valid for 1 hour. Starter plan and above. 1 call.",
    "parameters": [
     {
      "name": "vin",
      "in": "query",
      "required": true,
      "description": "The 17-character VIN",
      "schema": {
       "type": "string",
       "minLength": 17,
       "maxLength": 17
      },
      "example": "1FTFW5L85TKD66889"
     }
    ],
    "responses": {
     "200": {
      "description": "Original window sticker",
      "headers": {
       "X-Quota-Remaining": {
        "schema": {
         "type": "integer"
        },
        "description": "Calls left this month"
       },
       "X-Plan": {
        "schema": {
         "type": "string"
        },
        "description": "The key's plan"
       }
      },
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Sticker"
        },
        "example": {
         "vin": "1FTFW5L85TKD66889",
         "vehicle": {
          "vin": "1FTFW5L85TKD66889",
          "year": 2026,
          "make": "FORD",
          "model": "F-150",
          "trim": "Lariat",
          "trimSource": "Sticker"
         },
         "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": "Equipment Group 501A",
            "price": 2670,
            "priceText": "$2,670",
            "includes": [
             "Lariat Series"
            ]
           },
           {
            "name": "Lariat Black Appearance Pkg",
            "price": 1475,
            "priceText": "$1,475"
           },
           {
            "name": "Tow/Haul Package",
            "price": 1010,
            "priceText": "$1,010",
            "includes": [
             ".integrated Trailer Brake Cont",
             "Extended Range 36GAL Fuel Tank"
            ]
           }
          ],
          "discounts": [],
          "standardEquipment": [
           "Daytime Running Lamps",
           "Fully Boxed Steel Frame",
           "Headlamps - Auto High Beam"
          ]
         },
         "paint": {
          "location": "the Safety Compliance Certification label on the driver door jamb (B-pillar)",
          "codeOnFile": false,
          "code": null,
          "colorName": "Agate Black Metallic",
          "locked": false
         },
         "pdf": {
          "url": "https://stickerbyvin.com/api/v1/pdf/<signed-token>",
          "expiresAt": "2026-11-17T12:00:00.000Z"
         }
        }
       }
      }
     },
     "400": {
      "description": "Invalid VIN",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "Missing or invalid key",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "Key disabled, or the endpoint needs a paid plan",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "404": {
      "description": "Unknown VIN, or no original sticker available",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Rate limited or monthly quota used",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "502": {
      "description": "Upstream VIN database unavailable",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "securitySchemes": {
   "bearerAuth": {
    "type": "http",
    "scheme": "bearer",
    "description": "Your API key, sbv_live_... (free at https://stickerbyvin.com/developers)"
   }
  },
  "schemas": {
   "Error": {
    "type": "object",
    "properties": {
     "error": {
      "type": "object",
      "required": [
       "code",
       "message"
      ],
      "properties": {
       "code": {
        "type": "string",
        "enum": [
         "missing_key",
         "invalid_key",
         "key_disabled",
         "plan_required",
         "invalid_vin",
         "unknown_vin",
         "sticker_not_available",
         "rate_limited",
         "quota_exceeded",
         "upstream_unavailable",
         "internal"
        ]
       },
       "message": {
        "type": "string"
       }
      }
     }
    }
   },
   "Vehicle": {
    "type": "object",
    "properties": {
     "vin": {
      "type": [
       "string",
       "null"
      ]
     },
     "make": {
      "type": [
       "string",
       "null"
      ]
     },
     "model": {
      "type": [
       "string",
       "null"
      ]
     },
     "trim": {
      "type": [
       "string",
       "null"
      ]
     },
     "trimSource": {
      "type": [
       "string",
       "null"
      ]
     },
     "series": {
      "type": [
       "string",
       "null"
      ]
     },
     "bodyClass": {
      "type": [
       "string",
       "null"
      ]
     },
     "driveType": {
      "type": [
       "string",
       "null"
      ]
     },
     "engine": {
      "type": [
       "string",
       "null"
      ]
     },
     "fuel": {
      "type": [
       "string",
       "null"
      ]
     },
     "transmission": {
      "type": [
       "string",
       "null"
      ]
     },
     "doors": {
      "type": [
       "string",
       "null"
      ]
     },
     "plant": {
      "type": [
       "string",
       "null"
      ]
     },
     "manufacturer": {
      "type": [
       "string",
       "null"
      ]
     },
     "vehicleType": {
      "type": [
       "string",
       "null"
      ]
     },
     "gvwr": {
      "type": [
       "string",
       "null"
      ]
     },
     "electrification": {
      "type": [
       "string",
       "null"
      ]
     },
     "year": {
      "type": [
       "integer",
       "null"
      ]
     }
    }
   },
   "Paint": {
    "type": "object",
    "properties": {
     "location": {
      "type": "string"
     },
     "looksLike": {
      "type": "string"
     },
     "guideUrl": {
      "type": "string"
     },
     "codeOnFile": {
      "type": "boolean"
     },
     "code": {
      "type": [
       "string",
       "null"
      ]
     },
     "colorName": {
      "type": [
       "string",
       "null"
      ]
     },
     "locked": {
      "type": "boolean"
     },
     "note": {
      "type": [
       "string",
       "null"
      ]
     }
    }
   },
   "Decode": {
    "type": "object",
    "properties": {
     "vin": {
      "type": "string"
     },
     "vehicle": {
      "$ref": "#/components/schemas/Vehicle"
     },
     "recallCount": {
      "type": "integer"
     }
    }
   },
   "Availability": {
    "type": "object",
    "properties": {
     "vin": {
      "type": "string"
     },
     "vehicle": {
      "$ref": "#/components/schemas/Vehicle"
     },
     "originalSticker": {
      "type": "object",
      "properties": {
       "onFile": {
        "type": "boolean"
       },
       "source": {
        "type": [
         "string",
         "null"
        ]
       },
       "tier": {
        "type": [
         "string",
         "null"
        ]
       },
       "status": {
        "type": "string"
       },
       "note": {
        "type": [
         "string",
         "null"
        ]
       }
      }
     },
     "factoryDataSticker": {
      "type": "object",
      "properties": {
       "available": {
        "type": "boolean"
       },
       "label": {
        "type": "string"
       }
      }
     },
     "recallCount": {
      "type": "integer"
     },
     "paint": {
      "$ref": "#/components/schemas/Paint"
     },
     "checkedAt": {
      "type": "string",
      "format": "date-time"
     }
    }
   },
   "Sticker": {
    "type": "object",
    "properties": {
     "vin": {
      "type": "string"
     },
     "vehicle": {
      "$ref": "#/components/schemas/Vehicle"
     },
     "source": {
      "type": [
       "string",
       "null"
      ]
     },
     "original": {
      "type": "boolean",
      "description": "false for a carmaker's sticker copy stamped 'Unofficial Copy'"
     },
     "sticker": {
      "type": "object",
      "properties": {
       "description": {
        "type": [
         "string",
         "null"
        ]
       },
       "exteriorColor": {
        "type": [
         "string",
         "null"
        ]
       },
       "interiorColor": {
        "type": [
         "string",
         "null"
        ]
       },
       "engine": {
        "type": [
         "string",
         "null"
        ]
       },
       "transmission": {
        "type": [
         "string",
         "null"
        ]
       },
       "basePrice": {
        "type": [
         "number",
         "null"
        ]
       },
       "destination": {
        "type": [
         "number",
         "null"
        ]
       },
       "totalOptions": {
        "type": [
         "number",
         "null"
        ]
       },
       "totalMsrp": {
        "type": [
         "number",
         "null"
        ]
       },
       "fuelEconomy": {
        "type": [
         "object",
         "null"
        ]
       },
       "assemblyPlant": {
        "type": [
         "string",
         "null"
        ]
       },
       "options": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "name": {
           "type": "string"
          },
          "price": {
           "type": [
            "number",
            "null"
           ]
          },
          "priceText": {
           "type": [
            "string",
            "null"
           ]
          },
          "includes": {
           "type": "array",
           "items": {
            "type": "string"
           }
          }
         }
        }
       },
       "discounts": {
        "type": "array",
        "items": {
         "type": "object"
        }
       },
       "standardEquipment": {
        "type": "array",
        "items": {
         "type": "string"
        }
       }
      }
     },
     "paint": {
      "$ref": "#/components/schemas/Paint"
     },
     "pdf": {
      "type": "object",
      "properties": {
       "url": {
        "type": "string"
       },
       "expiresAt": {
        "type": "string",
        "format": "date-time"
       }
      }
     }
    }
   }
  }
 }
}
