{
 "openapi": "3.1.0",
 "info": {
  "title": "Third Row Reality spec feed",
  "version": "1.0.0",
  "description": "Read-only, provenance-complete specifications for luxury 3-row SUVs. Every value carries manufacturer source URLs; unknowns are explicit nulls with reasons (never estimates); source disagreements are served verbatim. Free with attribution — see the terms.",
  "license": {
   "name": "TRR-Attribution-1.0 (draft)",
   "url": "https://thirdrowreality.com/terms-of-use/"
  },
  "contact": {
   "url": "https://thirdrowreality.com/developers/"
  }
 },
 "servers": [
  {
   "url": "https://thirdrowreality-api.sntricity.workers.dev"
  }
 ],
 "paths": {
  "/v1/models": {
   "get": {
    "operationId": "listModels",
    "summary": "Model directory with stable slugs",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "data",
          "meta"
         ],
         "properties": {
          "data": {
           "type": "array",
           "items": {
            "type": "object",
            "required": [
             "slug",
             "displayName",
             "make",
             "modelYear",
             "bodyStyle",
             "powertrainType",
             "thirdRowAvailability"
            ],
            "properties": {
             "slug": {
              "type": "string",
              "enum": [
               "gls",
               "x7",
               "q7",
               "tx",
               "xc90",
               "r1s",
               "escalade",
               "navigator",
               "range-rover",
               "qx80",
               "mdx",
               "aviator",
               "gv80"
              ],
              "description": "Stable public ID — same slugs as thirdrowreality.com/models/{slug}/. A public contract; never renamed."
             },
             "displayName": {
              "type": "string"
             },
             "make": {
              "type": "string"
             },
             "modelYear": {
              "type": "integer"
             },
             "bodyStyle": {
              "type": "string",
              "enum": [
               "crossover",
               "body-on-frame",
               "unibody-suv"
              ]
             },
             "powertrainType": {
              "type": "string",
              "enum": [
               "gas",
               "hybrid",
               "phev",
               "ev"
              ]
             },
             "thirdRowAvailability": {
              "type": "string",
              "enum": [
               "standard",
               "lwb-only",
               "trim-optional"
              ]
             }
            }
           }
          },
          "meta": {
           "type": "object",
           "required": [
            "license",
            "attribution_url",
            "terms_url",
            "generated_at",
            "store_version"
           ],
           "properties": {
            "license": {
             "type": "string",
             "example": "TRR-Attribution-1.0 (draft)"
            },
            "attribution_url": {
             "type": "string",
             "format": "uri"
            },
            "terms_url": {
             "type": "string",
             "format": "uri"
            },
            "generated_at": {
             "type": "string",
             "format": "date-time"
            },
            "store_version": {
             "type": "string",
             "description": "Content hash of the dataset; changes exactly when the data changes."
            }
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/v1/models/{slug}": {
   "get": {
    "operationId": "getModel",
    "summary": "Full spec sheet: every field with provenance, safety block, persona scores",
    "parameters": [
     {
      "name": "slug",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "gls",
        "x7",
        "q7",
        "tx",
        "xc90",
        "r1s",
        "escalade",
        "navigator",
        "range-rover",
        "qx80",
        "mdx",
        "aviator",
        "gv80"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "data",
          "meta"
         ],
         "properties": {
          "data": {
           "type": "object"
          },
          "meta": {
           "type": "object",
           "required": [
            "license",
            "attribution_url",
            "terms_url",
            "generated_at",
            "store_version"
           ],
           "properties": {
            "license": {
             "type": "string",
             "example": "TRR-Attribution-1.0 (draft)"
            },
            "attribution_url": {
             "type": "string",
             "format": "uri"
            },
            "terms_url": {
             "type": "string",
             "format": "uri"
            },
            "generated_at": {
             "type": "string",
             "format": "date-time"
            },
            "store_version": {
             "type": "string",
             "description": "Content hash of the dataset; changes exactly when the data changes."
            }
           }
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Unknown slug; body lists valid slugs.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "error"
         ],
         "properties": {
          "error": {
           "type": "string"
          },
          "known_slugs_hint": {
           "type": "array",
           "items": {
            "type": "string"
           }
          },
          "known_fields": {
           "type": "array",
           "items": {
            "type": "string"
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/v1/models/{slug}/fields/{field}": {
   "get": {
    "operationId": "getField",
    "summary": "One field with full provenance and any disagreement records",
    "parameters": [
     {
      "name": "slug",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "gls",
        "x7",
        "q7",
        "tx",
        "xc90",
        "r1s",
        "escalade",
        "navigator",
        "range-rover",
        "qx80",
        "mdx",
        "aviator",
        "gv80"
       ]
      }
     },
     {
      "name": "field",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "enum": [
        "msrpMin",
        "msrpMax",
        "row1LegroomIn",
        "row2LegroomIn",
        "row3LegroomIn",
        "row3HeadroomIn",
        "cargoBehindRow3Cuft",
        "cargoBehindRow2Cuft",
        "cargoMaxCuft",
        "towingMaxLbs",
        "seatingMax",
        "lengthIn",
        "widthIn",
        "heightIn",
        "secondRowConfig",
        "curtainAirbagRow3Coverage",
        "latchLowerAnchorsRow3",
        "topTetherPositionsRow3",
        "seatbeltReminderRow3"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK — data is a spec-domain or safety-domain field object.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "data",
          "meta"
         ],
         "properties": {
          "data": {
           "oneOf": [
            {
             "type": "object",
             "description": "Dimensional/pricing field. Carries per-source verified booleans; nulls are explicit and carry availability.",
             "required": [
              "domain",
              "value",
              "unit",
              "verified",
              "sources"
             ],
             "properties": {
              "domain": {
               "type": "string",
               "const": "spec"
              },
              "value": {
               "oneOf": [
                {
                 "type": "number"
                },
                {
                 "type": "string"
                },
                {
                 "type": "null"
                }
               ]
              },
              "unit": {
               "oneOf": [
                {
                 "type": "string"
                },
                {
                 "type": "null"
                }
               ]
              },
              "verified": {
               "type": "boolean"
              },
              "availability": {
               "type": "object",
               "description": "Present only when value is null: why the value is absent.",
               "required": [
                "status",
                "note"
               ],
               "properties": {
                "status": {
                 "type": "string",
                 "enum": [
                  "not-published",
                  "pending"
                 ],
                 "description": "\"not-published\": the manufacturer omits this figure (reason in note). \"pending\": published but not yet sourced by this site."
                },
                "note": {
                 "type": "string"
                }
               }
              },
              "sources": {
               "type": "array",
               "items": {
                "type": "object",
                "required": [
                 "label",
                 "url",
                 "verified"
                ],
                "properties": {
                 "label": {
                  "type": "string"
                 },
                 "url": {
                  "type": "string",
                  "format": "uri"
                 },
                 "verified": {
                  "type": "boolean"
                 },
                 "note": {
                  "type": "string"
                 }
                }
               }
              }
             }
            },
            {
             "type": "object",
             "description": "Third-row safety hardware field. Carries the safety module’s three-state verification status plus stale-source flags; disagreements between sources are served verbatim, never arbitrated.",
             "required": [
              "domain",
              "value",
              "unit",
              "verificationStatus",
              "sources"
             ],
             "properties": {
              "domain": {
               "type": "string",
               "const": "safety"
              },
              "value": {
               "oneOf": [
                {
                 "type": "number"
                },
                {
                 "type": "boolean"
                },
                {
                 "type": "null"
                }
               ]
              },
              "unit": {
               "oneOf": [
                {
                 "type": "string"
                },
                {
                 "type": "null"
                }
               ]
              },
              "verificationStatus": {
               "type": "string",
               "enum": [
                "verified",
                "partial",
                "todo_verify"
               ]
              },
              "availability": {
               "type": "object",
               "description": "Present only when value is null: why the value is absent.",
               "required": [
                "status",
                "note"
               ],
               "properties": {
                "status": {
                 "type": "string",
                 "enum": [
                  "not-published",
                  "pending"
                 ],
                 "description": "\"not-published\": the manufacturer omits this figure (reason in note). \"pending\": published but not yet sourced by this site."
                },
                "note": {
                 "type": "string"
                }
               }
              },
              "disagreement": {
               "type": "object",
               "required": [
                "note"
               ],
               "properties": {
                "display": {
                 "type": "string"
                },
                "note": {
                 "type": "string"
                }
               }
              },
              "sources": {
               "type": "array",
               "items": {
                "type": "object",
                "required": [
                 "label",
                 "url",
                 "fields",
                 "sourceModelYear",
                 "staleSource",
                 "accessedDate"
                ],
                "properties": {
                 "label": {
                  "type": "string"
                 },
                 "url": {
                  "type": "string",
                  "format": "uri"
                 },
                 "fields": {
                  "type": "array",
                  "items": {
                   "type": "string"
                  }
                 },
                 "sourceModelYear": {
                  "oneOf": [
                   {
                    "type": "integer"
                   },
                   {
                    "type": "null"
                   }
                  ]
                 },
                 "staleSource": {
                  "type": "boolean",
                  "description": "True when the document describes a prior generation."
                 },
                 "accessedDate": {
                  "oneOf": [
                   {
                    "type": "string"
                   },
                   {
                    "type": "null"
                   }
                  ]
                 },
                 "note": {
                  "type": "string"
                 }
                }
               }
              }
             }
            }
           ]
          },
          "meta": {
           "type": "object",
           "required": [
            "license",
            "attribution_url",
            "terms_url",
            "generated_at",
            "store_version"
           ],
           "properties": {
            "license": {
             "type": "string",
             "example": "TRR-Attribution-1.0 (draft)"
            },
            "attribution_url": {
             "type": "string",
             "format": "uri"
            },
            "terms_url": {
             "type": "string",
             "format": "uri"
            },
            "generated_at": {
             "type": "string",
             "format": "date-time"
            },
            "store_version": {
             "type": "string",
             "description": "Content hash of the dataset; changes exactly when the data changes."
            }
           }
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Unknown slug or field; body lists valid values.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "error"
         ],
         "properties": {
          "error": {
           "type": "string"
          },
          "known_slugs_hint": {
           "type": "array",
           "items": {
            "type": "string"
           }
          },
          "known_fields": {
           "type": "array",
           "items": {
            "type": "string"
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/v1/compare": {
   "get": {
    "operationId": "compareModels",
    "summary": "Aligned comparison with per-cell provenance",
    "parameters": [
     {
      "name": "models",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Comma-separated slugs, at least two."
     },
     {
      "name": "fields",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Comma-separated field keys."
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "data",
          "meta"
         ],
         "properties": {
          "data": {
           "type": "object"
          },
          "meta": {
           "type": "object",
           "required": [
            "license",
            "attribution_url",
            "terms_url",
            "generated_at",
            "store_version"
           ],
           "properties": {
            "license": {
             "type": "string",
             "example": "TRR-Attribution-1.0 (draft)"
            },
            "attribution_url": {
             "type": "string",
             "format": "uri"
            },
            "terms_url": {
             "type": "string",
             "format": "uri"
            },
            "generated_at": {
             "type": "string",
             "format": "date-time"
            },
            "store_version": {
             "type": "string",
             "description": "Content hash of the dataset; changes exactly when the data changes."
            }
           }
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Missing parameters.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "error"
         ],
         "properties": {
          "error": {
           "type": "string"
          },
          "known_slugs_hint": {
           "type": "array",
           "items": {
            "type": "string"
           }
          },
          "known_fields": {
           "type": "array",
           "items": {
            "type": "string"
           }
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Unknown slug or field.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "error"
         ],
         "properties": {
          "error": {
           "type": "string"
          },
          "known_slugs_hint": {
           "type": "array",
           "items": {
            "type": "string"
           }
          },
          "known_fields": {
           "type": "array",
           "items": {
            "type": "string"
           }
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/v1/meta": {
   "get": {
    "operationId": "getMeta",
    "summary": "Dataset stats and verification-status breakdown",
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "required": [
          "data",
          "meta"
         ],
         "properties": {
          "data": {
           "type": "object"
          },
          "meta": {
           "type": "object",
           "required": [
            "license",
            "attribution_url",
            "terms_url",
            "generated_at",
            "store_version"
           ],
           "properties": {
            "license": {
             "type": "string",
             "example": "TRR-Attribution-1.0 (draft)"
            },
            "attribution_url": {
             "type": "string",
             "format": "uri"
            },
            "terms_url": {
             "type": "string",
             "format": "uri"
            },
            "generated_at": {
             "type": "string",
             "format": "date-time"
            },
            "store_version": {
             "type": "string",
             "description": "Content hash of the dataset; changes exactly when the data changes."
            }
           }
          }
         }
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "SpecField": {
    "type": "object",
    "description": "Dimensional/pricing field. Carries per-source verified booleans; nulls are explicit and carry availability.",
    "required": [
     "domain",
     "value",
     "unit",
     "verified",
     "sources"
    ],
    "properties": {
     "domain": {
      "type": "string",
      "const": "spec"
     },
     "value": {
      "oneOf": [
       {
        "type": "number"
       },
       {
        "type": "string"
       },
       {
        "type": "null"
       }
      ]
     },
     "unit": {
      "oneOf": [
       {
        "type": "string"
       },
       {
        "type": "null"
       }
      ]
     },
     "verified": {
      "type": "boolean"
     },
     "availability": {
      "type": "object",
      "description": "Present only when value is null: why the value is absent.",
      "required": [
       "status",
       "note"
      ],
      "properties": {
       "status": {
        "type": "string",
        "enum": [
         "not-published",
         "pending"
        ],
        "description": "\"not-published\": the manufacturer omits this figure (reason in note). \"pending\": published but not yet sourced by this site."
       },
       "note": {
        "type": "string"
       }
      }
     },
     "sources": {
      "type": "array",
      "items": {
       "type": "object",
       "required": [
        "label",
        "url",
        "verified"
       ],
       "properties": {
        "label": {
         "type": "string"
        },
        "url": {
         "type": "string",
         "format": "uri"
        },
        "verified": {
         "type": "boolean"
        },
        "note": {
         "type": "string"
        }
       }
      }
     }
    }
   },
   "SafetyField": {
    "type": "object",
    "description": "Third-row safety hardware field. Carries the safety module’s three-state verification status plus stale-source flags; disagreements between sources are served verbatim, never arbitrated.",
    "required": [
     "domain",
     "value",
     "unit",
     "verificationStatus",
     "sources"
    ],
    "properties": {
     "domain": {
      "type": "string",
      "const": "safety"
     },
     "value": {
      "oneOf": [
       {
        "type": "number"
       },
       {
        "type": "boolean"
       },
       {
        "type": "null"
       }
      ]
     },
     "unit": {
      "oneOf": [
       {
        "type": "string"
       },
       {
        "type": "null"
       }
      ]
     },
     "verificationStatus": {
      "type": "string",
      "enum": [
       "verified",
       "partial",
       "todo_verify"
      ]
     },
     "availability": {
      "type": "object",
      "description": "Present only when value is null: why the value is absent.",
      "required": [
       "status",
       "note"
      ],
      "properties": {
       "status": {
        "type": "string",
        "enum": [
         "not-published",
         "pending"
        ],
        "description": "\"not-published\": the manufacturer omits this figure (reason in note). \"pending\": published but not yet sourced by this site."
       },
       "note": {
        "type": "string"
       }
      }
     },
     "disagreement": {
      "type": "object",
      "required": [
       "note"
      ],
      "properties": {
       "display": {
        "type": "string"
       },
       "note": {
        "type": "string"
       }
      }
     },
     "sources": {
      "type": "array",
      "items": {
       "type": "object",
       "required": [
        "label",
        "url",
        "fields",
        "sourceModelYear",
        "staleSource",
        "accessedDate"
       ],
       "properties": {
        "label": {
         "type": "string"
        },
        "url": {
         "type": "string",
         "format": "uri"
        },
        "fields": {
         "type": "array",
         "items": {
          "type": "string"
         }
        },
        "sourceModelYear": {
         "oneOf": [
          {
           "type": "integer"
          },
          {
           "type": "null"
          }
         ]
        },
        "staleSource": {
         "type": "boolean",
         "description": "True when the document describes a prior generation."
        },
        "accessedDate": {
         "oneOf": [
          {
           "type": "string"
          },
          {
           "type": "null"
          }
         ]
        },
        "note": {
         "type": "string"
        }
       }
      }
     }
    }
   },
   "ModelIndexEntry": {
    "type": "object",
    "required": [
     "slug",
     "displayName",
     "make",
     "modelYear",
     "bodyStyle",
     "powertrainType",
     "thirdRowAvailability"
    ],
    "properties": {
     "slug": {
      "type": "string",
      "enum": [
       "gls",
       "x7",
       "q7",
       "tx",
       "xc90",
       "r1s",
       "escalade",
       "navigator",
       "range-rover",
       "qx80",
       "mdx",
       "aviator",
       "gv80"
      ],
      "description": "Stable public ID — same slugs as thirdrowreality.com/models/{slug}/. A public contract; never renamed."
     },
     "displayName": {
      "type": "string"
     },
     "make": {
      "type": "string"
     },
     "modelYear": {
      "type": "integer"
     },
     "bodyStyle": {
      "type": "string",
      "enum": [
       "crossover",
       "body-on-frame",
       "unibody-suv"
      ]
     },
     "powertrainType": {
      "type": "string",
      "enum": [
       "gas",
       "hybrid",
       "phev",
       "ev"
      ]
     },
     "thirdRowAvailability": {
      "type": "string",
      "enum": [
       "standard",
       "lwb-only",
       "trim-optional"
      ]
     }
    }
   },
   "Error": {
    "type": "object",
    "required": [
     "error"
    ],
    "properties": {
     "error": {
      "type": "string"
     },
     "known_slugs_hint": {
      "type": "array",
      "items": {
       "type": "string"
      }
     },
     "known_fields": {
      "type": "array",
      "items": {
       "type": "string"
      }
     }
    }
   }
  }
 }
}