{
  "openapi": "3.1.0",
  "info": {
    "title": "YMMFit Fitment API",
    "version": "1.0.0",
    "summary": "Vehicle-to-part compatibility for car audio and 12V installation accessories.",
    "description": "Answers which wiring harness, dash kit or fascia, steering-wheel-control adapter, antenna adapter, reverse camera, parking sensor or CarPlay/Android Auto retrofit module fits a given vehicle.\n\nThe dataset holds 483,653 vehicle-to-part links across 64,820 vehicles (1995-2026, 140 makes) and 20,874 parts, normalized from manufacturer application data published by Metra, Connects2, PAC, Scosche, Crux, Aerpro, iDatalink, CARAV and others.\n\nThis is not a TecDoc substitute and does not overlap with it: TecDoc covers mechanical and service parts, this covers installation compatibility. No TecDoc licence is required.\n\nAccess tiers:\n- The vehicle taxonomy (`/makes`, `/models`) is complete, free and usable in production without a key.\n- Fitment (`/parts`) is served from a public sandbox covering BMW, VW, Mercedes, Ford, Chevrolet and Toyota from 2012 onward. Full-catalog access is issued on request at https://ymmfit.com/fitment-api#access.\n\nNo authentication is required for any endpoint listed here.",
    "termsOfService": "https://ymmfit.com/terms",
    "contact": {
      "name": "YMMFit",
      "url": "https://ymmfit.com/fitment-api",
      "email": "hello@ymmfit.com"
    }
  },
  "servers": [
    {
      "url": "https://ymmfit.com/v1",
      "description": "Public sandbox"
    }
  ],
  "externalDocs": {
    "description": "Documentation, live sandbox and key requests",
    "url": "https://ymmfit.com/fitment-api"
  },
  "tags": [
    {
      "name": "Taxonomy",
      "description": "Vehicle list. Complete and free."
    },
    {
      "name": "Fitment",
      "description": "Vehicle-to-part compatibility. Sandbox coverage without a key."
    }
  ],
  "paths": {
    "/meta": {
      "get": {
        "tags": [
          "Taxonomy"
        ],
        "summary": "Catalog size and sandbox coverage",
        "description": "Totals for the full catalog, the part categories and contributing sources, and exactly which makes and years the public sandbox covers.",
        "operationId": "getMeta",
        "responses": {
          "200": {
            "description": "Catalog metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Meta"
                }
              }
            }
          }
        }
      }
    },
    "/makes": {
      "get": {
        "tags": [
          "Taxonomy"
        ],
        "summary": "List all makes",
        "description": "Every make in the catalog with its model count, vehicle count and year range. Complete — not limited to the sandbox.",
        "operationId": "listMakes",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Case-insensitive substring filter on the make name.",
            "schema": {
              "type": "string",
              "maxLength": 60
            },
            "example": "merc"
          }
        ],
        "responses": {
          "200": {
            "description": "Matching makes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "count",
                    "makes"
                  ],
                  "properties": {
                    "count": {
                      "type": "integer",
                      "example": 140
                    },
                    "makes": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Make"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/models": {
      "get": {
        "tags": [
          "Taxonomy"
        ],
        "summary": "List models for a make",
        "description": "Every model under one make, with the years each was built. Complete — not limited to the sandbox.",
        "operationId": "listModels",
        "parameters": [
          {
            "name": "make",
            "in": "query",
            "required": true,
            "description": "Make slug as returned by `/makes` (lowercase, hyphenated).",
            "schema": {
              "type": "string",
              "maxLength": 60
            },
            "example": "bmw"
          }
        ],
        "responses": {
          "200": {
            "description": "Models under the make",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "make",
                    "count",
                    "models"
                  ],
                  "properties": {
                    "make": {
                      "type": "string",
                      "example": "BMW"
                    },
                    "count": {
                      "type": "integer",
                      "example": 61
                    },
                    "models": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Model"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/parts": {
      "get": {
        "tags": [
          "Fitment"
        ],
        "summary": "Parts that fit one vehicle",
        "description": "Every compatible part for a single year/make/model, across all contributing brands.\n\nThe `note` field carries the qualifier under which the fitment holds — a chassis code such as `MK7`, or a condition such as `Non-amplified only`. Where `note` is absent the fitment is unconditional as published.\n\nWithout a key this is limited to the sandbox makes; a make that exists in the catalog but sits outside the sandbox returns `403 outside_sandbox` rather than an empty result, so a gap in access is never mistaken for a gap in the data.",
        "operationId": "listParts",
        "parameters": [
          {
            "name": "make",
            "in": "query",
            "required": true,
            "description": "Make slug as returned by `/makes`.",
            "schema": {
              "type": "string",
              "maxLength": 60
            },
            "example": "vw"
          },
          {
            "name": "model",
            "in": "query",
            "required": true,
            "description": "Model slug as returned by `/models`.",
            "schema": {
              "type": "string",
              "maxLength": 60
            },
            "example": "golf"
          },
          {
            "name": "year",
            "in": "query",
            "required": true,
            "description": "Four-digit model year.",
            "schema": {
              "type": "integer",
              "minimum": 1900,
              "maximum": 2100
            },
            "example": 2013
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Narrow the result to one part type.",
            "schema": {
              "$ref": "#/components/schemas/Category"
            },
            "example": "swc"
          }
        ],
        "responses": {
          "200": {
            "description": "Compatible parts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartsResponse"
                },
                "example": {
                  "vehicle": {
                    "year": 2013,
                    "make": "VW",
                    "model": "Golf"
                  },
                  "count": 23,
                  "parts": [
                    {
                      "mpn": "CAVW02",
                      "brand": "Aerpro",
                      "category": "swc",
                      "title": "Infodapter to suit Volkswagen",
                      "note": "MK7",
                      "source": "aerpro"
                    },
                    {
                      "mpn": "CHVW3C",
                      "brand": "Aerpro",
                      "category": "swc",
                      "title": "Steering wheel control interface",
                      "note": "MK6",
                      "source": "aerpro"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "description": "The make exists in the catalog but its fitment is outside the public sandbox.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "outside_sandbox",
                  "message": "Audi is in the catalog, but its fitment is not part of the public sandbox. Request a key for full coverage.",
                  "sandboxMakes": [
                    "bmw",
                    "vw",
                    "mercedes",
                    "ford",
                    "chevrolet",
                    "toyota"
                  ],
                  "requestKey": "https://ymmfit.com/fitment-api#access"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "BadRequest": {
        "description": "A required parameter is missing or malformed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "missing_parameter",
              "message": "Pass ?make=, ?model= and ?year= — for example /v1/parts?make=bmw&model=3-series&year=2018"
            }
          }
        }
      },
      "NotFound": {
        "description": "No such make, model or year.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "unknown_vehicle",
              "message": "No model \"3-serie\" under make \"bmw\". List them at /v1/models?make=bmw"
            }
          }
        }
      }
    },
    "schemas": {
      "Category": {
        "type": "string",
        "description": "Part type. Coverage is uneven: harness, dashkit, carplay, swc, speaker and antenna together are 93% of the catalog; camera, amp and aux are thinner; parking, dab and headunit are barely populated and will usually return an empty list. `swc` is a steering-wheel-control adapter; `dashkit` is a fascia/mounting kit; `carplay` is an Apple CarPlay or Android Auto retrofit module. Per-category counts are in /meta.",
        "enum": [
          "harness",
          "dashkit",
          "swc",
          "antenna",
          "camera",
          "parking",
          "carplay",
          "speaker",
          "amp",
          "headunit",
          "aux",
          "dab"
        ]
      },
      "Make": {
        "type": "object",
        "required": [
          "make",
          "slug",
          "models",
          "vehicles",
          "yearFrom",
          "yearTo",
          "fitmentInSandbox"
        ],
        "properties": {
          "make": {
            "type": "string",
            "example": "BMW"
          },
          "slug": {
            "type": "string",
            "description": "Use this value for the `make` parameter.",
            "example": "bmw"
          },
          "models": {
            "type": "integer",
            "example": 61
          },
          "vehicles": {
            "type": "integer",
            "description": "Distinct year/model combinations.",
            "example": 1204
          },
          "yearFrom": {
            "type": "integer",
            "example": 1995
          },
          "yearTo": {
            "type": "integer",
            "example": 2026
          },
          "fitmentInSandbox": {
            "type": "boolean",
            "description": "Whether `/parts` will answer for this make without a key.",
            "example": true
          }
        }
      },
      "Model": {
        "type": "object",
        "required": [
          "model",
          "slug",
          "years"
        ],
        "properties": {
          "model": {
            "type": "string",
            "example": "3 Series"
          },
          "slug": {
            "type": "string",
            "description": "Use this value for the `model` parameter.",
            "example": "3-series"
          },
          "years": {
            "type": "array",
            "description": "Every model year present in the catalog, ascending.",
            "items": {
              "type": "integer"
            },
            "example": [
              2012,
              2013,
              2014,
              2015
            ]
          }
        }
      },
      "Vehicle": {
        "type": "object",
        "required": [
          "year",
          "make",
          "model"
        ],
        "properties": {
          "year": {
            "type": "integer",
            "example": 2018
          },
          "make": {
            "type": "string",
            "example": "BMW"
          },
          "model": {
            "type": "string",
            "example": "3 Series"
          }
        }
      },
      "Part": {
        "type": "object",
        "required": [
          "mpn",
          "category"
        ],
        "properties": {
          "mpn": {
            "type": "string",
            "description": "Manufacturer part number.",
            "example": "CAVW02"
          },
          "brand": {
            "type": "string",
            "example": "Aerpro"
          },
          "category": {
            "$ref": "#/components/schemas/Category"
          },
          "title": {
            "type": "string",
            "example": "Infodapter to suit Volkswagen"
          },
          "note": {
            "type": "string",
            "description": "The qualifier under which this fitment holds — a chassis code such as \"MK7\", or a condition such as \"Non-amplified only\". Absent when the fitment is unconditional.",
            "example": "MK7"
          },
          "source": {
            "type": "string",
            "description": "Which manufacturer application guide this link came from.",
            "example": "aerpro"
          },
          "confidence": {
            "type": "integer",
            "description": "Present only when below 100, indicating a link inferred rather than published verbatim.",
            "minimum": 0,
            "maximum": 100
          }
        }
      },
      "PartsResponse": {
        "type": "object",
        "required": [
          "vehicle",
          "count",
          "parts"
        ],
        "properties": {
          "vehicle": {
            "$ref": "#/components/schemas/Vehicle"
          },
          "count": {
            "type": "integer",
            "example": 14
          },
          "parts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Part"
            }
          },
          "note": {
            "type": "string",
            "description": "Present only when a category filter returned nothing. States whether that is a gap in this vehicle or a gap in the catalog, so an empty list is never mistaken for a broken dataset."
          }
        }
      },
      "Meta": {
        "type": "object",
        "properties": {
          "api": {
            "type": "string",
            "example": "YMMFit Fitment API"
          },
          "version": {
            "type": "string",
            "example": "v1"
          },
          "access": {
            "type": "string",
            "example": "sandbox"
          },
          "docs": {
            "type": "string",
            "format": "uri"
          },
          "catalog": {
            "type": "object",
            "properties": {
              "vehicles": {
                "type": "integer",
                "example": 64820
              },
              "makes": {
                "type": "integer",
                "example": 140
              },
              "parts": {
                "type": "integer",
                "example": 20874
              },
              "fitments": {
                "type": "integer",
                "example": 483653
              },
              "yearFrom": {
                "type": "integer",
                "example": 1995
              },
              "yearTo": {
                "type": "integer",
                "example": 2026
              }
            }
          },
          "sandbox": {
            "type": "object",
            "properties": {
              "makes": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "yearFrom": {
                "type": "integer",
                "example": 2012
              },
              "fitments": {
                "type": "integer",
                "example": 98229
              },
              "note": {
                "type": "string"
              }
            }
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "category": {
                  "$ref": "#/components/schemas/Category"
                },
                "parts": {
                  "type": "integer"
                }
              }
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "source": {
                  "type": "string"
                },
                "fitments": {
                  "type": "integer"
                }
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "missing_parameter",
              "invalid_year",
              "invalid_category",
              "unknown_make",
              "unknown_vehicle",
              "unknown_year",
              "outside_sandbox",
              "not_found",
              "sandbox_unavailable",
              "internal"
            ]
          },
          "message": {
            "type": "string"
          },
          "availableYears": {
            "type": "array",
            "items": {
              "type": "integer"
            }
          },
          "sandboxMakes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "requestKey": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    }
  }
}