{
  "openapi": "3.1.0",
  "info": {
    "title": "CO Business List static data API",
    "version": "1.0.0",
    "description": "Read-only JSON files describing Colorado businesses listed on CO Business List (cobusinesslist.com). Static files, no key needed, cached for 1 hour. For people-facing pages use the HTML URLs in each response. Independent directory, not affiliated with the State of Colorado.",
    "contact": { "name": "CO Business List", "url": "https://cobusinesslist.com/contact/" }
  },
  "servers": [{ "url": "https://cobusinesslist.com" }],
  "paths": {
    "/api/business.json": {
      "get": {
        "operationId": "getDirectorySummary",
        "summary": "Directory summary: coverage counts, URL patterns and actions (add, claim, contact).",
        "responses": { "200": { "description": "Summary object", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/data/cats.json": {
      "get": {
        "operationId": "listCategories",
        "summary": "All 111 categories with slug (s), name (n), group (g), statewide count (c) and search keywords (k).",
        "responses": { "200": { "description": "Array of categories", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } } } } }
      }
    },
    "/data/cities.json": {
      "get": {
        "operationId": "listCities",
        "summary": "All 542 Colorado cities and towns with slug (s), name (n), business count (c), whether it has per-category pages (b) and pages per category (k).",
        "responses": { "200": { "description": "Array of cities", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/City" } } } } } }
      }
    },
    "/data/n/{prefix}.json": {
      "get": {
        "operationId": "findBusinessesByName",
        "summary": "Name index. prefix = first two letters/digits of the first word of the business name, skipping common words such as the, a, an, and, of, co, llc (lowercase, e.g. 'ch' for 'Choice City Locksmith'; single-letter words use the letter plus '_'). Returns rows of [name, citySlug, categorySlug, id, page, flags]. Build the listing URL as https://cobusinesslist.com/{citySlug}/{categorySlug}/ (add page/{page}/ when page > 1) and anchor #b-{id}. flags: bit 1 = has phone, bit 2 = has website.",
        "parameters": [{ "name": "prefix", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9_]{2}$" } }],
        "responses": { "200": { "description": "Array of name rows", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "array" } } } } }, "404": { "description": "No names start with that prefix" } }
      }
    }
  },
  "components": {
    "schemas": {
      "Category": { "type": "object", "properties": { "s": { "type": "string" }, "n": { "type": "string" }, "g": { "type": "string" }, "c": { "type": "integer" }, "k": { "type": "array", "items": { "type": "string" } } } },
      "City": { "type": "object", "properties": { "s": { "type": "string" }, "n": { "type": "string" }, "c": { "type": "integer" }, "b": { "type": "boolean" }, "k": { "type": "object", "additionalProperties": { "type": "integer" } } } }
    }
  }
}
