{
  "openapi": "3.1.0",
  "info": {
    "title": "TexasRatedPros API",
    "version": "1.0.0",
    "description": "Rankings of independent Texas service companies, computed from verified review data, state business-registration records, and licence checks. No key is required — the data is published to be quoted. Every response carries the date its data was read and a citation line. Rankings are a point-in-time assessment, not an endorsement or a guarantee of workmanship.",
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    },
    "termsOfService": "https://www.texasratedpros.com/api-terms"
  },
  "servers": [
    {
      "url": "https://www.texasratedpros.com"
    }
  ],
  "paths": {
    "/api/v1/meta": {
      "get": {
        "summary": "What exists and how to ask for it",
        "description": "Available metros and categories with their slugs, plus every endpoint URL. Start here.",
        "responses": {
          "200": {
            "description": "Available metros, categories, and endpoints",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "metros": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "region": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "categories": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "slug": {
                                  "type": "string"
                                },
                                "name": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "slug",
                                "name"
                              ],
                              "additionalProperties": false
                            }
                          }
                        },
                        "required": [
                          "slug",
                          "name",
                          "region",
                          "categories"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "categories": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "vertical": {
                            "type": "string"
                          },
                          "licensingNote": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "slug",
                          "name",
                          "vertical",
                          "licensingNote"
                        ],
                        "additionalProperties": false
                      }
                    }
                  },
                  "required": [
                    "metros",
                    "categories"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/rankings/{metro}/{category}": {
      "get": {
        "summary": "Get a ranking",
        "description": "The ranked list for one category in one metro. Franchise and chain locations are excluded by editorial policy; the count and the brand names are included in the response.",
        "parameters": [
          {
            "in": "path",
            "name": "metro",
            "schema": {
              "type": "string",
              "description": "Metro slug, e.g. austin"
            },
            "required": true,
            "description": "Metro slug, e.g. austin"
          },
          {
            "in": "path",
            "name": "category",
            "schema": {
              "type": "string",
              "description": "Category slug, e.g. house-cleaning"
            },
            "required": true,
            "description": "Category slug, e.g. house-cleaning"
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "in": "query",
            "name": "include_bubble",
            "schema": {
              "description": "Include eligible companies below the published cap",
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            },
            "description": "Include eligible companies below the published cap"
          }
        ],
        "responses": {
          "200": {
            "description": "The published ranking",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "metro": {
                      "type": "object",
                      "properties": {
                        "slug": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "region": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "slug",
                        "name",
                        "region"
                      ],
                      "additionalProperties": false
                    },
                    "category": {
                      "type": "object",
                      "properties": {
                        "slug": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "slug",
                        "name"
                      ],
                      "additionalProperties": false
                    },
                    "updatedAt": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "totalRanked": {
                      "type": "number"
                    },
                    "totalTracked": {
                      "type": "number"
                    },
                    "franchisesExcluded": {
                      "type": "number"
                    },
                    "excludedBrands": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "reviewsAnalyzed": {
                      "type": "number"
                    },
                    "marketMedianRating": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "companies": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "rank": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Null when tracked but not ranked"
                          },
                          "slug": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "city": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "trpScore": {
                            "type": "number"
                          },
                          "scoreBand": {
                            "type": "string"
                          },
                          "confidenceTier": {
                            "type": "string"
                          },
                          "rankChange": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Positions gained since the previous reconstitution"
                          },
                          "googleRating": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "googleReviewCount": {
                            "type": "number"
                          },
                          "yearsInBusiness": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "verifications": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "slug": {
                                  "type": "string"
                                },
                                "name": {
                                  "type": "string"
                                },
                                "authority": {
                                  "type": "string"
                                },
                                "idNumber": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "verifiedOn": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "verifyUrl": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "caveat": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ],
                                  "description": "What this credential does not prove"
                                }
                              },
                              "required": [
                                "slug",
                                "name",
                                "authority",
                                "idNumber",
                                "verifiedOn",
                                "verifyUrl",
                                "caveat"
                              ],
                              "additionalProperties": false
                            }
                          },
                          "disclosures": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "profileUrl": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "rank",
                          "slug",
                          "name",
                          "city",
                          "trpScore",
                          "scoreBand",
                          "confidenceTier",
                          "rankChange",
                          "googleRating",
                          "googleReviewCount",
                          "yearsInBusiness",
                          "verifications",
                          "disclosures",
                          "profileUrl"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "bubble": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "rank": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Null when tracked but not ranked"
                          },
                          "slug": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "city": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "trpScore": {
                            "type": "number"
                          },
                          "scoreBand": {
                            "type": "string"
                          },
                          "confidenceTier": {
                            "type": "string"
                          },
                          "rankChange": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "Positions gained since the previous reconstitution"
                          },
                          "googleRating": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "googleReviewCount": {
                            "type": "number"
                          },
                          "yearsInBusiness": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "verifications": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "slug": {
                                  "type": "string"
                                },
                                "name": {
                                  "type": "string"
                                },
                                "authority": {
                                  "type": "string"
                                },
                                "idNumber": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "verifiedOn": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "verifyUrl": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                },
                                "caveat": {
                                  "anyOf": [
                                    {
                                      "type": "string"
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ],
                                  "description": "What this credential does not prove"
                                }
                              },
                              "required": [
                                "slug",
                                "name",
                                "authority",
                                "idNumber",
                                "verifiedOn",
                                "verifyUrl",
                                "caveat"
                              ],
                              "additionalProperties": false
                            }
                          },
                          "disclosures": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "profileUrl": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "rank",
                          "slug",
                          "name",
                          "city",
                          "trpScore",
                          "scoreBand",
                          "confidenceTier",
                          "rankChange",
                          "googleRating",
                          "googleReviewCount",
                          "yearsInBusiness",
                          "verifications",
                          "disclosures",
                          "profileUrl"
                        ],
                        "additionalProperties": false
                      },
                      "description": "Eligible companies below the published cap; scores shown, ranks withheld"
                    },
                    "provenance": {
                      "type": "object",
                      "properties": {
                        "asOf": {
                          "type": "string",
                          "description": "ISO date the underlying data was last refreshed"
                        },
                        "methodologyVersion": {
                          "type": "string"
                        },
                        "sourceUrl": {
                          "type": "string",
                          "description": "Canonical HTML page for this answer"
                        },
                        "sourceMarkdownUrl": {
                          "type": "string",
                          "description": "Markdown twin of the same page"
                        },
                        "citeAs": {
                          "type": "string",
                          "description": "Ready-made citation line"
                        }
                      },
                      "required": [
                        "asOf",
                        "methodologyVersion",
                        "sourceUrl",
                        "sourceMarkdownUrl",
                        "citeAs"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "metro",
                    "category",
                    "updatedAt",
                    "totalRanked",
                    "totalTracked",
                    "franchisesExcluded",
                    "excludedBrands",
                    "reviewsAnalyzed",
                    "marketMedianRating",
                    "companies",
                    "bubble",
                    "provenance"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "404": {
            "description": "No published ranking for that combination",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/businesses": {
      "get": {
        "summary": "Search companies",
        "parameters": [
          {
            "in": "query",
            "name": "query",
            "schema": {
              "description": "Part of a company name",
              "type": "string"
            },
            "description": "Part of a company name"
          },
          {
            "in": "query",
            "name": "metro",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "category",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "min_score",
            "schema": {
              "type": "number",
              "minimum": 0,
              "maximum": 100
            }
          },
          {
            "in": "query",
            "name": "verified_only",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          },
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching companies, best score first",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "total": {
                      "type": "number"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "city": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "trpScore": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "googleRating": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "googleReviewCount": {
                            "type": "number"
                          },
                          "bestRank": {
                            "anyOf": [
                              {
                                "type": "object",
                                "properties": {
                                  "rank": {
                                    "type": "number"
                                  },
                                  "outOf": {
                                    "type": "number"
                                  },
                                  "metro": {
                                    "type": "string"
                                  },
                                  "category": {
                                    "type": "string"
                                  }
                                },
                                "required": [
                                  "rank",
                                  "outOf",
                                  "metro",
                                  "category"
                                ],
                                "additionalProperties": false
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "profileUrl": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "slug",
                          "name",
                          "city",
                          "trpScore",
                          "googleRating",
                          "googleReviewCount",
                          "bestRank",
                          "profileUrl"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "provenance": {
                      "type": "object",
                      "properties": {
                        "asOf": {
                          "type": "string",
                          "description": "ISO date the underlying data was last refreshed"
                        },
                        "methodologyVersion": {
                          "type": "string"
                        },
                        "sourceUrl": {
                          "type": "string",
                          "description": "Canonical HTML page for this answer"
                        },
                        "sourceMarkdownUrl": {
                          "type": "string",
                          "description": "Markdown twin of the same page"
                        },
                        "citeAs": {
                          "type": "string",
                          "description": "Ready-made citation line"
                        }
                      },
                      "required": [
                        "asOf",
                        "methodologyVersion",
                        "sourceUrl",
                        "sourceMarkdownUrl",
                        "citeAs"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "total",
                    "results",
                    "provenance"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/businesses/{slug}": {
      "get": {
        "summary": "Get a company profile",
        "description": "The full record: score breakdown by pillar, what was verified and by which authority, what could not be verified, and every ranking the company appears in.",
        "parameters": [
          {
            "in": "path",
            "name": "slug",
            "schema": {
              "type": "string"
            },
            "required": true
          }
        ],
        "responses": {
          "200": {
            "description": "The company",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "slug": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "legalName": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "city": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "region": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "website": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "phone": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "establishedOn": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "establishedSource": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Which record the founding date came from"
                    },
                    "yearsInBusiness": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "googleRating": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "googleReviewCount": {
                      "type": "number"
                    },
                    "ratingDistribution": {
                      "anyOf": [
                        {
                          "type": "object",
                          "propertyNames": {
                            "type": "string"
                          },
                          "additionalProperties": {
                            "type": "number"
                          }
                        },
                        {
                          "type": "null"
                        }
                      ],
                      "description": "Counts per star, 1 through 5"
                    },
                    "ownerResponseRate": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "trpScore": {
                      "anyOf": [
                        {
                          "type": "number"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "scoreBand": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "pillars": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "pillar": {
                            "type": "string",
                            "enum": [
                              "reputation",
                              "volume",
                              "longevity",
                              "trust",
                              "engagement"
                            ]
                          },
                          "weight": {
                            "type": "number"
                          },
                          "score": {
                            "type": "number",
                            "description": "Pillar score in [0,1]"
                          },
                          "contribution": {
                            "type": "number",
                            "description": "Points this pillar added to the total"
                          }
                        },
                        "required": [
                          "pillar",
                          "weight",
                          "score",
                          "contribution"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "rankings": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "metro": {
                            "type": "string"
                          },
                          "metroSlug": {
                            "type": "string"
                          },
                          "category": {
                            "type": "string"
                          },
                          "categorySlug": {
                            "type": "string"
                          },
                          "rank": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "outOf": {
                            "type": "number"
                          },
                          "trpScore": {
                            "type": "number"
                          },
                          "url": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "metro",
                          "metroSlug",
                          "category",
                          "categorySlug",
                          "rank",
                          "outOf",
                          "trpScore",
                          "url"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "verifications": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "authority": {
                            "type": "string"
                          },
                          "idNumber": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "verifiedOn": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "verifyUrl": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "caveat": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ],
                            "description": "What this credential does not prove"
                          }
                        },
                        "required": [
                          "slug",
                          "name",
                          "authority",
                          "idNumber",
                          "verifiedOn",
                          "verifyUrl",
                          "caveat"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "notVerified": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "authority": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "slug",
                          "name",
                          "authority"
                        ],
                        "additionalProperties": false
                      },
                      "description": "Checklist items this company does not hold"
                    },
                    "disclosures": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "corrections": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "occurredAt": {
                            "type": "string"
                          },
                          "note": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "occurredAt",
                          "note"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "provenance": {
                      "type": "object",
                      "properties": {
                        "asOf": {
                          "type": "string",
                          "description": "ISO date the underlying data was last refreshed"
                        },
                        "methodologyVersion": {
                          "type": "string"
                        },
                        "sourceUrl": {
                          "type": "string",
                          "description": "Canonical HTML page for this answer"
                        },
                        "sourceMarkdownUrl": {
                          "type": "string",
                          "description": "Markdown twin of the same page"
                        },
                        "citeAs": {
                          "type": "string",
                          "description": "Ready-made citation line"
                        }
                      },
                      "required": [
                        "asOf",
                        "methodologyVersion",
                        "sourceUrl",
                        "sourceMarkdownUrl",
                        "citeAs"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "slug",
                    "name",
                    "legalName",
                    "city",
                    "region",
                    "website",
                    "phone",
                    "establishedOn",
                    "establishedSource",
                    "yearsInBusiness",
                    "googleRating",
                    "googleReviewCount",
                    "ratingDistribution",
                    "ownerResponseRate",
                    "trpScore",
                    "scoreBand",
                    "pillars",
                    "rankings",
                    "verifications",
                    "notVerified",
                    "disclosures",
                    "corrections",
                    "provenance"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "404": {
            "description": "No company with that slug",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/compare": {
      "get": {
        "summary": "Compare companies",
        "parameters": [
          {
            "in": "query",
            "name": "slugs",
            "schema": {
              "type": "string",
              "description": "Two to four comma-separated company slugs"
            },
            "required": true,
            "description": "Two to four comma-separated company slugs"
          },
          {
            "in": "query",
            "name": "metro",
            "schema": {
              "description": "Shared metro context when more than one exists",
              "type": "string"
            },
            "description": "Shared metro context when more than one exists"
          },
          {
            "in": "query",
            "name": "category",
            "schema": {
              "description": "Shared category context when more than one exists",
              "type": "string"
            },
            "description": "Shared category context when more than one exists"
          }
        ],
        "responses": {
          "200": {
            "description": "Side-by-side comparison with a verdict",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "requiresContext": {
                      "type": "boolean"
                    },
                    "context": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "metro": {
                              "type": "string"
                            },
                            "metroSlug": {
                              "type": "string"
                            },
                            "category": {
                              "type": "string"
                            },
                            "categorySlug": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "metro",
                            "metroSlug",
                            "category",
                            "categorySlug"
                          ],
                          "additionalProperties": false
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "availableContexts": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "metro": {
                            "type": "string"
                          },
                          "metroSlug": {
                            "type": "string"
                          },
                          "category": {
                            "type": "string"
                          },
                          "categorySlug": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "metro",
                          "metroSlug",
                          "category",
                          "categorySlug"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "companies": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "slug": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "rank": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "outOf": {
                            "type": "number"
                          },
                          "trpScore": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "scoreBand": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "googleRating": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "googleReviewCount": {
                            "type": "number"
                          },
                          "yearsInBusiness": {
                            "anyOf": [
                              {
                                "type": "number"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "verifications": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "profileUrl": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "slug",
                          "name",
                          "rank",
                          "outOf",
                          "trpScore",
                          "scoreBand",
                          "googleRating",
                          "googleReviewCount",
                          "yearsInBusiness",
                          "verifications",
                          "profileUrl"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "pillarComparison": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "pillar": {
                            "type": "string",
                            "enum": [
                              "reputation",
                              "volume",
                              "longevity",
                              "trust",
                              "engagement"
                            ]
                          },
                          "weight": {
                            "type": "number"
                          },
                          "scores": {
                            "type": "object",
                            "propertyNames": {
                              "type": "string"
                            },
                            "additionalProperties": {
                              "type": "number"
                            }
                          },
                          "leader": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "pillar",
                          "weight",
                          "scores",
                          "leader"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "verdict": {
                      "type": "string",
                      "description": "One sentence naming the leader and why"
                    },
                    "provenance": {
                      "type": "object",
                      "properties": {
                        "asOf": {
                          "type": "string",
                          "description": "ISO date the underlying data was last refreshed"
                        },
                        "methodologyVersion": {
                          "type": "string"
                        },
                        "sourceUrl": {
                          "type": "string",
                          "description": "Canonical HTML page for this answer"
                        },
                        "sourceMarkdownUrl": {
                          "type": "string",
                          "description": "Markdown twin of the same page"
                        },
                        "citeAs": {
                          "type": "string",
                          "description": "Ready-made citation line"
                        }
                      },
                      "required": [
                        "asOf",
                        "methodologyVersion",
                        "sourceUrl",
                        "sourceMarkdownUrl",
                        "citeAs"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "requiresContext",
                    "context",
                    "availableContexts",
                    "companies",
                    "pillarComparison",
                    "verdict",
                    "provenance"
                  ],
                  "additionalProperties": false
                }
              }
            }
          },
          "400": {
            "description": "Between two and four slugs are required",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "error"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/methodology": {
      "get": {
        "summary": "Get the ranking methodology",
        "description": "Exact weights, thresholds, eligibility rules, data sources, and stated limitations. Read this before characterising what a score means.",
        "responses": {
          "200": {
            "description": "The published methodology",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "version": {
                      "type": "string"
                    },
                    "effectiveDate": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "summary": {
                      "type": "string"
                    },
                    "pillars": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "pillar": {
                            "type": "string",
                            "enum": [
                              "reputation",
                              "volume",
                              "longevity",
                              "trust",
                              "engagement"
                            ]
                          },
                          "name": {
                            "type": "string"
                          },
                          "weight": {
                            "type": "number"
                          },
                          "rationale": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "pillar",
                          "name",
                          "weight",
                          "rationale"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "scoreBands": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "min": {
                            "type": "number"
                          },
                          "label": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "min",
                          "label"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "eligibility": {
                      "type": "object",
                      "properties": {
                        "minReviewsToList": {
                          "type": "number"
                        },
                        "minReviewsToRank": {
                          "type": "number"
                        },
                        "minReviewAgeMonths": {
                          "type": "number"
                        },
                        "minRating": {
                          "type": "number"
                        },
                        "entityMatchRequired": {
                          "type": "boolean"
                        },
                        "franchisesExcluded": {
                          "type": "boolean",
                          "const": true
                        }
                      },
                      "required": [
                        "minReviewsToList",
                        "minReviewsToRank",
                        "minReviewAgeMonths",
                        "minRating",
                        "entityMatchRequired",
                        "franchisesExcluded"
                      ],
                      "additionalProperties": false
                    },
                    "reputation": {
                      "type": "object",
                      "properties": {
                        "halfLifeDays": {
                          "type": "number"
                        },
                        "priorReviews": {
                          "type": "number",
                          "description": "Phantom reviews every company starts with, at the market median"
                        },
                        "priorStatistic": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "halfLifeDays",
                        "priorReviews",
                        "priorStatistic"
                      ],
                      "additionalProperties": false
                    },
                    "ranking": {
                      "type": "object",
                      "properties": {
                        "listSize": {
                          "type": "number"
                        },
                        "swapThreshold": {
                          "type": "number"
                        },
                        "entryThreshold": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "listSize",
                        "swapThreshold",
                        "entryThreshold"
                      ],
                      "additionalProperties": false
                    },
                    "dataSources": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "provider": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "cadence": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "caveat": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "name",
                          "provider",
                          "cadence",
                          "caveat"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "limitations": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "provenance": {
                      "type": "object",
                      "properties": {
                        "asOf": {
                          "type": "string",
                          "description": "ISO date the underlying data was last refreshed"
                        },
                        "methodologyVersion": {
                          "type": "string"
                        },
                        "sourceUrl": {
                          "type": "string",
                          "description": "Canonical HTML page for this answer"
                        },
                        "sourceMarkdownUrl": {
                          "type": "string",
                          "description": "Markdown twin of the same page"
                        },
                        "citeAs": {
                          "type": "string",
                          "description": "Ready-made citation line"
                        }
                      },
                      "required": [
                        "asOf",
                        "methodologyVersion",
                        "sourceUrl",
                        "sourceMarkdownUrl",
                        "citeAs"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "version",
                    "effectiveDate",
                    "summary",
                    "pillars",
                    "scoreBands",
                    "eligibility",
                    "reputation",
                    "ranking",
                    "dataSources",
                    "limitations",
                    "provenance"
                  ],
                  "additionalProperties": false
                }
              }
            }
          }
        }
      }
    }
  }
}