{
  "openapi": "3.1.0",
  "info": {
    "title": "townhall.town API",
    "version": "1.0.0",
    "summary": "Nonpartisan, sourced ballot data for the Nov 3, 2026 U.S. general election.",
    "description": "Free, no key, no account. Covered ZIPs: 78701 (Austin, Texas), 94103 (San Francisco, California), 10001 (New York, New York). Every fact carries a source link; facts that cannot be confirmed are marked unsure. Every API error is JSON: {\"error\":{\"code\",\"message\"}}.\n\nVersioning and deprecation: The API is versioned in the URL path (/api/v1/...). Every response carries API-Version. Non-breaking changes (new optional fields, new endpoints) ship in place. Breaking changes ship under a new /api/vN path; the previous version keeps working for at least 90 days after the new one launches, and during that time its responses carry Deprecation (RFC 9745) and Sunset (RFC 8594) headers plus a Link to this policy. The unversioned /api/agent and /api/locate paths are aliases of /api/v1 and follow the same policy. Policy: https://townhall.town/developers#versioning\n\nRate limits: per client IP, fixed 60-second window: 10 requests per minute on the ballot agent, 30 on locate, 10 on /api/research and 10 on /api/interview. Counters are kept in memory per server instance, so the limit is approximate, not a guarantee. Every response carries RateLimit-Policy and RateLimit (draft-ietf-httpapi-ratelimit-headers) and RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. Over the limit you get 429 with Retry-After and the usual JSON error body (code rate_limited).",
    "license": {
      "name": "MIT",
      "identifier": "MIT"
    },
    "contact": {
      "name": "GitHub issues",
      "url": "https://github.com/adamtpang/townhall.town/issues"
    }
  },
  "x-api-versioning": {
    "current": "v1",
    "strategy": "url-path",
    "summary": "The API is versioned in the URL path (/api/v1/...). Every response carries API-Version. Non-breaking changes (new optional fields, new endpoints) ship in place. Breaking changes ship under a new /api/vN path; the previous version keeps working for at least 90 days after the new one launches, and during that time its responses carry Deprecation (RFC 9745) and Sunset (RFC 8594) headers plus a Link to this policy. The unversioned /api/agent and /api/locate paths are aliases of /api/v1 and follow the same policy.",
    "minimumNoticeDays": 90,
    "header": "API-Version",
    "deprecationHeaders": [
      "Deprecation (RFC 9745)",
      "Sunset (RFC 8594)",
      "Link rel=\"deprecation\""
    ],
    "policyUrl": "https://townhall.town/developers#versioning"
  },
  "x-rate-limits": {
    "headers": [
      "RateLimit-Policy",
      "RateLimit",
      "RateLimit-Limit",
      "RateLimit-Remaining",
      "RateLimit-Reset",
      "Retry-After"
    ],
    "scope": "per client IP, per server instance (approximate, not guaranteed)",
    "policies": [
      {
        "name": "agent",
        "limit": 10,
        "windowSeconds": 60
      },
      {
        "name": "locate",
        "limit": 30,
        "windowSeconds": 60
      },
      {
        "name": "research",
        "limit": 10,
        "windowSeconds": 60
      },
      {
        "name": "interview",
        "limit": 10,
        "windowSeconds": 60
      }
    ]
  },
  "externalDocs": {
    "description": "townhall.town API and developer docs, with curl examples",
    "url": "https://townhall.town/developers"
  },
  "servers": [
    {
      "url": "https://townhall.town"
    }
  ],
  "security": [],
  "tags": [
    {
      "name": "ballot",
      "description": "Races, candidates, measures and sources for a covered ZIP."
    },
    {
      "name": "location",
      "description": "Coordinates to ZIP via the U.S. Census Geocoder."
    },
    {
      "name": "research",
      "description": "The site's live helpers: candidates' own words on chosen issues, and turning a voter's words into issue answers."
    }
  ],
  "paths": {
    "/api/v1/agent": {
      "get": {
        "operationId": "getBallot",
        "tags": [
          "ballot"
        ],
        "summary": "Explain the ballot for a ZIP",
        "description": "Runs the ballot agent for a ZIP: districts, races, candidates, live Polymarket prices and local Census data, plus a short neutral AI summary written only from those records. Responses are not cached (Cache-Control: no-store). Rate limited per client: see RateLimit headers.",
        "parameters": [
          {
            "name": "zip",
            "in": "query",
            "required": true,
            "description": "Exactly 5 digits.",
            "schema": {
              "type": "string",
              "pattern": "^\\d{5}$",
              "examples": [
                "78701",
                "94103",
                "10001"
              ]
            }
          },
          {
            "name": "Accept",
            "in": "header",
            "required": false,
            "description": "Omit (or send application/x-ndjson) for the live stream. Send application/json for one buffered JSON object with the final event.",
            "schema": {
              "type": "string",
              "examples": [
                "application/x-ndjson",
                "application/json"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The ballot run. Default (Accept: */* or application/x-ndjson): a stream of newline-delimited JSON, one AgentEvent per line. Step and status events arrive while tools run; the stream ends with one `result` event, or one `unsupported` event for a 5-digit ZIP that is not covered, or one `error` event if the run fails after the stream started. With `Accept: application/json` (preferred over NDJSON) the server waits for the run and returns only the final event as one JSON object (ResultEvent or UnsupportedEvent; a failed run is a 500 Error).",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Vary": {
                "description": "Always Accept: the media type depends on it.",
                "schema": {
                  "type": "string",
                  "const": "Accept"
                }
              }
            },
            "content": {
              "application/x-ndjson": {
                "schema": {
                  "$ref": "#/components/schemas/AgentEvent"
                },
                "x-ndjson-item-schema": {
                  "$ref": "#/components/schemas/AgentEvent"
                },
                "example": {
                  "type": "unsupported",
                  "zip": "90210",
                  "message": "Austin, SF and NYC for now."
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentFinalEvent"
                },
                "example": {
                  "type": "unsupported",
                  "zip": "90210",
                  "message": "Austin, SF and NYC for now."
                }
              }
            }
          },
          "400": {
            "description": "The zip is not exactly 5 digits, or the body is not JSON. Nothing is trimmed or sliced.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid",
                    "message": "zip must be exactly 5 digits, for example 78701."
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed. The Allow header lists the supported methods.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "Allow": {
                "description": "Supported methods.",
                "schema": {
                  "type": "string",
                  "example": "GET, POST"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "method_not_allowed",
                    "message": "Method not allowed. Use GET or POST."
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limited: more than 10 requests in 60 seconds from this client. Wait Retry-After seconds.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many requests: the limit is 10 per 60 seconds per client. Retry after 42 seconds."
                  }
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error, or (JSON mode only) the agent run failed.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "internal",
                    "message": "Unexpected server error."
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "postBallot",
        "tags": [
          "ballot"
        ],
        "summary": "Explain the ballot for a ZIP (JSON body)",
        "description": "Same as GET, with the ZIP in a JSON body. The townhall.town page calls the /api/agent alias this way.",
        "parameters": [
          {
            "name": "Accept",
            "in": "header",
            "required": false,
            "description": "Omit (or send application/x-ndjson) for the live stream. Send application/json for one buffered JSON object with the final event.",
            "schema": {
              "type": "string",
              "examples": [
                "application/x-ndjson",
                "application/json"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "zip"
                ],
                "properties": {
                  "zip": {
                    "type": "string",
                    "pattern": "^\\d{5}$",
                    "description": "Exactly 5 digits, as a string."
                  }
                }
              },
              "example": {
                "zip": "78701"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The ballot run. Default (Accept: */* or application/x-ndjson): a stream of newline-delimited JSON, one AgentEvent per line. Step and status events arrive while tools run; the stream ends with one `result` event, or one `unsupported` event for a 5-digit ZIP that is not covered, or one `error` event if the run fails after the stream started. With `Accept: application/json` (preferred over NDJSON) the server waits for the run and returns only the final event as one JSON object (ResultEvent or UnsupportedEvent; a failed run is a 500 Error).",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Vary": {
                "description": "Always Accept: the media type depends on it.",
                "schema": {
                  "type": "string",
                  "const": "Accept"
                }
              }
            },
            "content": {
              "application/x-ndjson": {
                "schema": {
                  "$ref": "#/components/schemas/AgentEvent"
                },
                "x-ndjson-item-schema": {
                  "$ref": "#/components/schemas/AgentEvent"
                },
                "example": {
                  "type": "unsupported",
                  "zip": "90210",
                  "message": "Austin, SF and NYC for now."
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentFinalEvent"
                },
                "example": {
                  "type": "unsupported",
                  "zip": "90210",
                  "message": "Austin, SF and NYC for now."
                }
              }
            }
          },
          "400": {
            "description": "The zip is not exactly 5 digits, or the body is not JSON. Nothing is trimmed or sliced.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid",
                    "message": "zip must be exactly 5 digits, for example 78701."
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed. The Allow header lists the supported methods.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "Allow": {
                "description": "Supported methods.",
                "schema": {
                  "type": "string",
                  "example": "GET, POST"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "method_not_allowed",
                    "message": "Method not allowed. Use GET or POST."
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limited: more than 10 requests in 60 seconds from this client. Wait Retry-After seconds.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many requests: the limit is 10 per 60 seconds per client. Retry after 42 seconds."
                  }
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error, or (JSON mode only) the agent run failed.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "internal",
                    "message": "Unexpected server error."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/locate": {
      "post": {
        "operationId": "locateZip",
        "tags": [
          "location"
        ],
        "summary": "Coordinates to ZIP",
        "description": "Looks up the ZIP Code Tabulation Area for a point using the public U.S. Census Geocoder. Coordinates are not stored. Rate limited per client: see RateLimit headers.",
        "requestBody": {
          "required": true,
          "description": "Coordinates go in the JSON body, not the URL, so they do not appear in request paths or logs of URLs.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "lat",
                  "lon"
                ],
                "properties": {
                  "lat": {
                    "type": "number",
                    "minimum": -90,
                    "maximum": 90,
                    "description": "Latitude in decimal degrees."
                  },
                  "lon": {
                    "type": "number",
                    "minimum": -180,
                    "maximum": 180,
                    "description": "Longitude in decimal degrees."
                  }
                }
              },
              "example": {
                "lat": 30.2672,
                "lon": -97.7431
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The ZIP for the point.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LocateResult"
                },
                "example": {
                  "zip": "78701",
                  "source": "U.S. Census Geocoder (ZCTA)"
                }
              }
            }
          },
          "400": {
            "description": "The body is not JSON, or lat or lon is missing or out of range.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid",
                    "message": "Send a JSON body {\"lat\": <number>, \"lon\": <number>} in decimal degrees (lat -90..90, lon -180..180)."
                  }
                }
              }
            }
          },
          "404": {
            "description": "The point is not inside a U.S. ZIP Code Tabulation Area.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "No ZIP found for this location"
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed. The Allow header lists the supported methods.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "Allow": {
                "description": "Supported methods.",
                "schema": {
                  "type": "string",
                  "example": "POST"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "method_not_allowed",
                    "message": "Method not allowed. Use POST."
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limited: more than 30 requests in 60 seconds from this client. Wait Retry-After seconds.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many requests: the limit is 30 per 60 seconds per client. Retry after 42 seconds."
                  }
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error, or (JSON mode only) the agent run failed.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "internal",
                    "message": "Unexpected server error."
                  }
                }
              }
            }
          },
          "502": {
            "description": "The Census Geocoder did not answer.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "upstream_unavailable",
                    "message": "Census geocoder unavailable"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/agent": {
      "get": {
        "operationId": "getBallotUnversioned",
        "tags": [
          "ballot"
        ],
        "summary": "Explain the ballot for a ZIP (alias of /api/v1/agent)",
        "description": "Runs the ballot agent for a ZIP: districts, races, candidates, live Polymarket prices and local Census data, plus a short neutral AI summary written only from those records. Responses are not cached (Cache-Control: no-store). Rate limited per client: see RateLimit headers. Unversioned alias of /api/v1/agent with identical behavior. Prefer /api/v1/agent in new code.",
        "parameters": [
          {
            "name": "zip",
            "in": "query",
            "required": true,
            "description": "Exactly 5 digits.",
            "schema": {
              "type": "string",
              "pattern": "^\\d{5}$",
              "examples": [
                "78701",
                "94103",
                "10001"
              ]
            }
          },
          {
            "name": "Accept",
            "in": "header",
            "required": false,
            "description": "Omit (or send application/x-ndjson) for the live stream. Send application/json for one buffered JSON object with the final event.",
            "schema": {
              "type": "string",
              "examples": [
                "application/x-ndjson",
                "application/json"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The ballot run. Default (Accept: */* or application/x-ndjson): a stream of newline-delimited JSON, one AgentEvent per line. Step and status events arrive while tools run; the stream ends with one `result` event, or one `unsupported` event for a 5-digit ZIP that is not covered, or one `error` event if the run fails after the stream started. With `Accept: application/json` (preferred over NDJSON) the server waits for the run and returns only the final event as one JSON object (ResultEvent or UnsupportedEvent; a failed run is a 500 Error).",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Vary": {
                "description": "Always Accept: the media type depends on it.",
                "schema": {
                  "type": "string",
                  "const": "Accept"
                }
              }
            },
            "content": {
              "application/x-ndjson": {
                "schema": {
                  "$ref": "#/components/schemas/AgentEvent"
                },
                "x-ndjson-item-schema": {
                  "$ref": "#/components/schemas/AgentEvent"
                },
                "example": {
                  "type": "unsupported",
                  "zip": "90210",
                  "message": "Austin, SF and NYC for now."
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentFinalEvent"
                },
                "example": {
                  "type": "unsupported",
                  "zip": "90210",
                  "message": "Austin, SF and NYC for now."
                }
              }
            }
          },
          "400": {
            "description": "The zip is not exactly 5 digits, or the body is not JSON. Nothing is trimmed or sliced.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid",
                    "message": "zip must be exactly 5 digits, for example 78701."
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed. The Allow header lists the supported methods.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "Allow": {
                "description": "Supported methods.",
                "schema": {
                  "type": "string",
                  "example": "GET, POST"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "method_not_allowed",
                    "message": "Method not allowed. Use GET or POST."
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limited: more than 10 requests in 60 seconds from this client. Wait Retry-After seconds.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many requests: the limit is 10 per 60 seconds per client. Retry after 42 seconds."
                  }
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error, or (JSON mode only) the agent run failed.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "internal",
                    "message": "Unexpected server error."
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "postBallotUnversioned",
        "tags": [
          "ballot"
        ],
        "summary": "Explain the ballot for a ZIP, JSON body (alias of /api/v1/agent)",
        "description": "Same as GET, with the ZIP in a JSON body. The townhall.town page calls the /api/agent alias this way. Unversioned alias of /api/v1/agent with identical behavior. Prefer /api/v1/agent in new code.",
        "parameters": [
          {
            "name": "Accept",
            "in": "header",
            "required": false,
            "description": "Omit (or send application/x-ndjson) for the live stream. Send application/json for one buffered JSON object with the final event.",
            "schema": {
              "type": "string",
              "examples": [
                "application/x-ndjson",
                "application/json"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "zip"
                ],
                "properties": {
                  "zip": {
                    "type": "string",
                    "pattern": "^\\d{5}$",
                    "description": "Exactly 5 digits, as a string."
                  }
                }
              },
              "example": {
                "zip": "78701"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The ballot run. Default (Accept: */* or application/x-ndjson): a stream of newline-delimited JSON, one AgentEvent per line. Step and status events arrive while tools run; the stream ends with one `result` event, or one `unsupported` event for a 5-digit ZIP that is not covered, or one `error` event if the run fails after the stream started. With `Accept: application/json` (preferred over NDJSON) the server waits for the run and returns only the final event as one JSON object (ResultEvent or UnsupportedEvent; a failed run is a 500 Error).",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Vary": {
                "description": "Always Accept: the media type depends on it.",
                "schema": {
                  "type": "string",
                  "const": "Accept"
                }
              }
            },
            "content": {
              "application/x-ndjson": {
                "schema": {
                  "$ref": "#/components/schemas/AgentEvent"
                },
                "x-ndjson-item-schema": {
                  "$ref": "#/components/schemas/AgentEvent"
                },
                "example": {
                  "type": "unsupported",
                  "zip": "90210",
                  "message": "Austin, SF and NYC for now."
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentFinalEvent"
                },
                "example": {
                  "type": "unsupported",
                  "zip": "90210",
                  "message": "Austin, SF and NYC for now."
                }
              }
            }
          },
          "400": {
            "description": "The zip is not exactly 5 digits, or the body is not JSON. Nothing is trimmed or sliced.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid",
                    "message": "zip must be exactly 5 digits, for example 78701."
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed. The Allow header lists the supported methods.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "Allow": {
                "description": "Supported methods.",
                "schema": {
                  "type": "string",
                  "example": "GET, POST"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "method_not_allowed",
                    "message": "Method not allowed. Use GET or POST."
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limited: more than 10 requests in 60 seconds from this client. Wait Retry-After seconds.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many requests: the limit is 10 per 60 seconds per client. Retry after 42 seconds."
                  }
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error, or (JSON mode only) the agent run failed.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "internal",
                    "message": "Unexpected server error."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/locate": {
      "post": {
        "operationId": "locateZipUnversioned",
        "tags": [
          "location"
        ],
        "summary": "Coordinates to ZIP (alias of /api/v1/locate)",
        "description": "Looks up the ZIP Code Tabulation Area for a point using the public U.S. Census Geocoder. Coordinates are not stored. Rate limited per client: see RateLimit headers. Unversioned alias of /api/v1/locate with identical behavior. Prefer /api/v1/locate in new code.",
        "requestBody": {
          "required": true,
          "description": "Coordinates go in the JSON body, not the URL, so they do not appear in request paths or logs of URLs.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "lat",
                  "lon"
                ],
                "properties": {
                  "lat": {
                    "type": "number",
                    "minimum": -90,
                    "maximum": 90,
                    "description": "Latitude in decimal degrees."
                  },
                  "lon": {
                    "type": "number",
                    "minimum": -180,
                    "maximum": 180,
                    "description": "Longitude in decimal degrees."
                  }
                }
              },
              "example": {
                "lat": 30.2672,
                "lon": -97.7431
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The ZIP for the point.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LocateResult"
                },
                "example": {
                  "zip": "78701",
                  "source": "U.S. Census Geocoder (ZCTA)"
                }
              }
            }
          },
          "400": {
            "description": "The body is not JSON, or lat or lon is missing or out of range.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid",
                    "message": "Send a JSON body {\"lat\": <number>, \"lon\": <number>} in decimal degrees (lat -90..90, lon -180..180)."
                  }
                }
              }
            }
          },
          "404": {
            "description": "The point is not inside a U.S. ZIP Code Tabulation Area.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "No ZIP found for this location"
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed. The Allow header lists the supported methods.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "Allow": {
                "description": "Supported methods.",
                "schema": {
                  "type": "string",
                  "example": "POST"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "method_not_allowed",
                    "message": "Method not allowed. Use POST."
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limited: more than 30 requests in 60 seconds from this client. Wait Retry-After seconds.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many requests: the limit is 30 per 60 seconds per client. Retry after 42 seconds."
                  }
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error, or (JSON mode only) the agent run failed.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "internal",
                    "message": "Unexpected server error."
                  }
                }
              }
            }
          },
          "502": {
            "description": "The Census Geocoder did not answer.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "upstream_unavailable",
                    "message": "Census geocoder unavailable"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/research": {
      "get": {
        "operationId": "researchRace",
        "tags": [
          "research"
        ],
        "summary": "Read each candidate's pages for their own words on chosen issues",
        "description": "For one race on a covered ZIP's ballot, reads each candidate's listed pages (campaign site, official site, Ballotpedia), issue pages linked from their own site, and web search results, the same way for every candidate. Returns only the candidate's own words, copied exactly from the page with its URL: sentences on their own campaign or official site, or words in quotation marks that a third-party page attributes to them by name. Nothing is scored. Judicial races return only a done event. Rate limited per client: see RateLimit headers.",
        "parameters": [
          {
            "name": "zip",
            "in": "query",
            "required": true,
            "description": "A covered ZIP, exactly 5 digits.",
            "schema": {
              "type": "string",
              "pattern": "^\\d{5}$",
              "examples": [
                "78701",
                "94103",
                "10001"
              ]
            }
          },
          {
            "name": "race",
            "in": "query",
            "required": true,
            "description": "A race id from the ballot result, e.g. ca-gov.",
            "schema": {
              "type": "string",
              "examples": [
                "ca-gov",
                "tx-sboe-5"
              ]
            }
          },
          {
            "name": "issues",
            "in": "query",
            "required": false,
            "description": "Comma-separated issue ids (housing, healthcare, wages, taxes, safety, education, energy, immigration, wealthtax, infrastructure). Default: all.",
            "schema": {
              "type": "string",
              "examples": [
                "housing,taxes"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A stream of newline-delimited JSON, one ResearchEvent per line, ending with a done event. Every response carries x-research-cache and x-research-cache-layer: hit/run when a complete earlier run on the same server instance is replayed; hit/search+pages when every web search and page for this race is already cached on this instance (no new searches or fetches); partial when some are; miss/none otherwise. Caches and rate-limit counters are per server instance, so two calls that land on different instances both read as miss and as the first call of the window.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "x-research-cache": {
                "description": "hit: answered entirely from this instance's caches (a replayed run, or every search and page already cached). partial: some searches or pages cached. miss: none.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "hit",
                    "partial",
                    "miss"
                  ]
                }
              },
              "x-research-cache-layer": {
                "description": "Which cache answered: run (whole earlier run replayed), search+pages (per-search and per-page caches), or none.",
                "schema": {
                  "type": "string",
                  "enum": [
                    "run",
                    "search+pages",
                    "none"
                  ]
                }
              }
            },
            "content": {
              "application/x-ndjson": {
                "schema": {
                  "$ref": "#/components/schemas/ResearchEvent"
                },
                "x-ndjson-item-schema": {
                  "$ref": "#/components/schemas/ResearchEvent"
                },
                "example": {
                  "type": "citation",
                  "name": "Xavier Becerra",
                  "issue": "housing",
                  "quote": "As governor, I will treat housing like the essential infrastructure it is.",
                  "url": "https://www.xavierbecerra2026.com/priorities/",
                  "ownSite": true
                }
              }
            }
          },
          "400": {
            "description": "The zip is not exactly 5 digits.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid",
                    "message": "zip must be exactly 5 digits, for example 78701."
                  }
                }
              }
            }
          },
          "404": {
            "description": "The race id is not on this ZIP's ballot.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Unknown race for this ZIP."
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed. The Allow header lists the supported methods.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "Allow": {
                "description": "Supported methods.",
                "schema": {
                  "type": "string",
                  "example": "GET"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "method_not_allowed",
                    "message": "Method not allowed. Use GET."
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limited: more than 10 requests in 60 seconds from this client. Wait Retry-After seconds.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many requests: the limit is 10 per 60 seconds per client. Retry after 42 seconds."
                  }
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error, or (JSON mode only) the agent run failed.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "internal",
                    "message": "Unexpected server error."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/interview": {
      "post": {
        "operationId": "interviewAnswers",
        "tags": [
          "research"
        ],
        "summary": "Turn what a voter wrote into Yes/Neutral/No issue answers",
        "description": "Maps the voter's own words to the fixed issue questions for a covered ZIP. Only questions the text clearly addresses are answered, each with the exact words that support it. Nothing the voter types is stored or logged. Rate limited per client: see RateLimit headers.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InterviewRequest"
              },
              "example": {
                "zip": "78701",
                "messages": [
                  {
                    "text": "Rent is too high and I'm unsure about taxes."
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The answers found (possibly none).",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InterviewResult"
                },
                "example": {
                  "answers": [
                    {
                      "issue": "housing",
                      "choice": "yes",
                      "words": "Rent is too high"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The body is not JSON, or the zip is not a covered 5-digit ZIP.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid",
                    "message": "zip must be one of the covered 5-digit ZIPs: 78701, 94103 or 10001."
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed. The Allow header lists the supported methods.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "Allow": {
                "description": "Supported methods.",
                "schema": {
                  "type": "string",
                  "example": "POST"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "method_not_allowed",
                    "message": "Method not allowed. Use POST."
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limited: more than 10 requests in 60 seconds from this client. Wait Retry-After seconds.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many requests: the limit is 10 per 60 seconds per client. Retry after 42 seconds."
                  }
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error, or (JSON mode only) the agent run failed.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "internal",
                    "message": "Unexpected server error."
                  }
                }
              }
            }
          },
          "502": {
            "description": "The answer model did not respond.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "upstream_unavailable",
                    "message": "The answer model did not respond. Try again."
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/towny/followup": {
      "post": {
        "operationId": "townyFollowup",
        "tags": [
          "research"
        ],
        "summary": "Answer a Towny follow-up question with sourced, self-checked facts",
        "description": "Routes a follow-up (a measure, why a candidate is listed first, a candidate's sourced positions, issue overlap, dates) to tools, then checks every factual sentence against curated data or sources fetched in the run. Unconfirmed sentences come back marked unsure. The ZIP and answers are sent by the client each time and are never stored or logged. Rate limited per client: see RateLimit headers.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TownyFollowupRequest"
              },
              "example": {
                "zip": "78701",
                "question": "What about Prop A?"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The answer, its verified claims and the self-check report.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TownyFollowupResult"
                },
                "example": {
                  "kind": "who",
                  "reply": "I don't pick for you. I can show where each candidate's sourced positions overlap with your answers.",
                  "claims": [],
                  "report": null,
                  "links": [],
                  "toolCalls": []
                }
              }
            }
          },
          "400": {
            "description": "The body is not JSON, or the question is missing.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid",
                    "message": "question is required."
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed. The Allow header lists the supported methods.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "Allow": {
                "description": "Supported methods.",
                "schema": {
                  "type": "string",
                  "example": "POST"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "method_not_allowed",
                    "message": "Method not allowed. Use POST."
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limited: more than 10 requests in 60 seconds from this client. Wait Retry-After seconds.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              },
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many requests: the limit is 10 per 60 seconds per client. Retry after 42 seconds."
                  }
                }
              }
            }
          },
          "500": {
            "description": "Unexpected server error, or (JSON mode only) the agent run failed.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "internal",
                    "message": "Unexpected server error."
                  }
                }
              }
            }
          },
          "502": {
            "description": "A tool failed.",
            "headers": {
              "API-Version": {
                "$ref": "#/components/headers/API-Version"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimit-Policy"
              },
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimit-Limit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimit-Remaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimit-Reset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "upstream_unavailable",
                    "message": "Towny couldn't check that right now. Try again."
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "headers": {
      "API-Version": {
        "description": "Major version of the API that served the response.",
        "schema": {
          "type": "string",
          "const": "1"
        }
      },
      "RateLimit-Policy": {
        "description": "Quota policy (draft-ietf-httpapi-ratelimit-headers): name, q = requests allowed, w = window in seconds. Example: \"agent\";q=10;w=60",
        "schema": {
          "type": "string",
          "examples": [
            "\"agent\";q=10;w=60",
            "\"locate\";q=30;w=60"
          ]
        }
      },
      "RateLimit": {
        "description": "Current service limit (draft-ietf-httpapi-ratelimit-headers): r = requests left, t = seconds until the window resets. Example: \"agent\";r=9;t=60",
        "schema": {
          "type": "string",
          "examples": [
            "\"agent\";r=9;t=60"
          ]
        }
      },
      "RateLimit-Limit": {
        "description": "Requests allowed per window.",
        "schema": {
          "type": "integer",
          "examples": [
            10
          ]
        }
      },
      "RateLimit-Remaining": {
        "description": "Requests left in the current window.",
        "schema": {
          "type": "integer",
          "minimum": 0,
          "examples": [
            9
          ]
        }
      },
      "RateLimit-Reset": {
        "description": "Seconds until the current window resets.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "examples": [
            60
          ]
        }
      },
      "Retry-After": {
        "description": "Seconds to wait before retrying (RFC 9110). Sent on 429.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "examples": [
            42
          ]
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "invalid",
                  "not_found",
                  "method_not_allowed",
                  "upstream_unavailable",
                  "rate_limited",
                  "internal"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        },
        "description": "Returned by every API route on error, including 404 for an unknown /api/* path."
      },
      "Source": {
        "type": "object",
        "required": [
          "label",
          "url"
        ],
        "properties": {
          "label": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "retrieved": {
            "type": "string"
          }
        }
      },
      "ResearchEvent": {
        "description": "One line of the /api/research stream.",
        "oneOf": [
          {
            "type": "object",
            "title": "candidate",
            "required": [
              "type",
              "name",
              "sources"
            ],
            "properties": {
              "type": {
                "const": "candidate"
              },
              "name": {
                "type": "string"
              },
              "sources": {
                "type": "integer",
                "minimum": 0
              }
            }
          },
          {
            "type": "object",
            "title": "step",
            "required": [
              "type",
              "name",
              "url",
              "label",
              "status"
            ],
            "properties": {
              "type": {
                "const": "step"
              },
              "name": {
                "type": "string"
              },
              "url": {
                "type": "string"
              },
              "label": {
                "type": "string"
              },
              "status": {
                "enum": [
                  "running",
                  "done",
                  "failed"
                ]
              },
              "detail": {
                "type": "string"
              }
            }
          },
          {
            "type": "object",
            "title": "citation",
            "required": [
              "type",
              "name",
              "issue",
              "quote",
              "url"
            ],
            "properties": {
              "type": {
                "const": "citation"
              },
              "name": {
                "type": "string"
              },
              "issue": {
                "type": "string"
              },
              "quote": {
                "type": "string",
                "description": "Exact substring of the page text."
              },
              "url": {
                "type": "string",
                "format": "uri"
              },
              "ownSite": {
                "type": "boolean",
                "description": "True when the page is on the candidate's own campaign or official site."
              }
            }
          },
          {
            "type": "object",
            "title": "none",
            "required": [
              "type",
              "name",
              "message"
            ],
            "properties": {
              "type": {
                "const": "none"
              },
              "name": {
                "type": "string"
              },
              "message": {
                "type": "string",
                "examples": [
                  "No public statement found as of Oct 29, 2026"
                ]
              }
            }
          },
          {
            "type": "object",
            "title": "done",
            "required": [
              "type"
            ],
            "properties": {
              "type": {
                "const": "done"
              },
              "judicial": {
                "type": "boolean"
              }
            }
          }
        ],
        "discriminator": {
          "propertyName": "type"
        }
      },
      "InterviewRequest": {
        "type": "object",
        "required": [
          "zip",
          "messages"
        ],
        "properties": {
          "zip": {
            "type": "string",
            "pattern": "^\\d{5}$",
            "examples": [
              "78701",
              "94103",
              "10001"
            ]
          },
          "messages": {
            "type": "array",
            "maxItems": 6,
            "description": "The voter's messages, newest last. Only the last 6 are read, each up to 600 characters.",
            "items": {
              "type": "object",
              "required": [
                "text"
              ],
              "properties": {
                "text": {
                  "type": "string",
                  "maxLength": 600
                }
              }
            }
          }
        }
      },
      "TownyFollowupRequest": {
        "type": "object",
        "required": [
          "zip",
          "question"
        ],
        "properties": {
          "zip": {
            "type": "string"
          },
          "question": {
            "type": "string"
          },
          "answers": {
            "type": "object",
            "additionalProperties": {
              "type": [
                "number",
                "null"
              ]
            }
          },
          "races": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "focus": {
            "type": "object",
            "properties": {
              "raceId": {
                "type": "string"
              },
              "candidate": {
                "type": "string"
              },
              "measureId": {
                "type": "string"
              }
            }
          }
        }
      },
      "TownyFollowupResult": {
        "type": "object",
        "required": [
          "kind",
          "reply"
        ],
        "properties": {
          "kind": {
            "type": "string"
          },
          "reply": {
            "type": "string"
          },
          "claims": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "report": {
            "type": [
              "object",
              "null"
            ]
          },
          "links": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "toolCalls": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "InterviewResult": {
        "type": "object",
        "required": [
          "answers"
        ],
        "properties": {
          "answers": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "issue",
                "choice",
                "words"
              ],
              "properties": {
                "issue": {
                  "type": "string"
                },
                "choice": {
                  "enum": [
                    "yes",
                    "neutral",
                    "no"
                  ]
                },
                "words": {
                  "type": "string",
                  "description": "The voter's own words that support this answer."
                }
              }
            }
          }
        }
      },
      "LocateResult": {
        "type": "object",
        "required": [
          "zip",
          "source"
        ],
        "properties": {
          "zip": {
            "type": "string",
            "pattern": "^\\d{5}$"
          },
          "source": {
            "type": "string",
            "const": "U.S. Census Geocoder (ZCTA)"
          }
        }
      },
      "AgentFinalEvent": {
        "description": "The final event of a run, returned alone as application/json when the client sends Accept: application/json.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/ResultEvent"
          },
          {
            "$ref": "#/components/schemas/UnsupportedEvent"
          }
        ],
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "result": "#/components/schemas/ResultEvent",
            "unsupported": "#/components/schemas/UnsupportedEvent"
          }
        }
      },
      "AgentEvent": {
        "description": "One line of the NDJSON stream (application/x-ndjson): each line is one JSON object matching this schema.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/StepEvent"
          },
          {
            "$ref": "#/components/schemas/StatusEvent"
          },
          {
            "$ref": "#/components/schemas/ResultEvent"
          },
          {
            "$ref": "#/components/schemas/UnsupportedEvent"
          },
          {
            "$ref": "#/components/schemas/ErrorEvent"
          }
        ],
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "step": "#/components/schemas/StepEvent",
            "status": "#/components/schemas/StatusEvent",
            "result": "#/components/schemas/ResultEvent",
            "unsupported": "#/components/schemas/UnsupportedEvent",
            "error": "#/components/schemas/ErrorEvent"
          }
        }
      },
      "StepEvent": {
        "type": "object",
        "required": [
          "type",
          "tool",
          "label",
          "status"
        ],
        "properties": {
          "type": {
            "const": "step"
          },
          "tool": {
            "type": "string",
            "enum": [
              "getDistricts",
              "getRaces",
              "getCandidates",
              "getMarketOdds",
              "getLocalProblems",
              "getCampaignFinance",
              "getCountyUnemployment",
              "analyze"
            ]
          },
          "label": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "running",
              "done"
            ]
          },
          "input": {
            "description": "Tool input, on running events."
          },
          "ms": {
            "type": "integer",
            "description": "Tool time, on done events."
          },
          "summary": {
            "type": "string",
            "description": "One-line result, on done events."
          }
        }
      },
      "StatusEvent": {
        "type": "object",
        "required": [
          "type",
          "message"
        ],
        "properties": {
          "type": {
            "const": "status"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "UnsupportedEvent": {
        "type": "object",
        "required": [
          "type",
          "zip",
          "message"
        ],
        "properties": {
          "type": {
            "const": "unsupported"
          },
          "zip": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "ErrorEvent": {
        "type": "object",
        "required": [
          "type",
          "message"
        ],
        "properties": {
          "type": {
            "const": "error"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "ResultEvent": {
        "type": "object",
        "required": [
          "type",
          "mode",
          "model",
          "modelError",
          "toolsRunByModel",
          "narration",
          "ballot",
          "markets",
          "generatedAt"
        ],
        "properties": {
          "type": {
            "const": "result"
          },
          "mode": {
            "type": "string",
            "enum": [
              "live",
              "fallback"
            ],
            "description": "live: a model planned the tool calls. fallback: the same tools ran with no model."
          },
          "model": {
            "type": [
              "string",
              "null"
            ]
          },
          "modelError": {
            "type": [
              "string",
              "null"
            ]
          },
          "toolsRunByModel": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "narration": {
            "type": "string",
            "description": "Neutral summary written from the tool results only. Empty in fallback mode."
          },
          "ballot": {
            "$ref": "#/components/schemas/Ballot"
          },
          "markets": {
            "type": "object",
            "description": "Live Polymarket prices keyed by race or measure id, fetched at request time from Polymarket's public Gamma API. Polymarket is the only market source. Market prices, not forecasts. No cached or estimated numbers: status 'no market found' (Polymarket has no market on that contest) or 'unavailable' (the live fetch failed) come with an empty quotes array.",
            "additionalProperties": {
              "type": "object",
              "required": [
                "status",
                "quotes"
              ],
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "live",
                    "unavailable",
                    "no market found",
                    "market does not list every ballot candidate"
                  ]
                },
                "quotes": {
                  "type": "array",
                  "maxItems": 1,
                  "items": {
                    "type": "object",
                    "required": [
                      "source",
                      "title",
                      "url",
                      "api",
                      "outcomes",
                      "fetchedAt"
                    ],
                    "properties": {
                      "source": {
                        "const": "Polymarket"
                      },
                      "title": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string",
                        "format": "uri",
                        "description": "The Polymarket event page."
                      },
                      "api": {
                        "type": "string",
                        "format": "uri"
                      },
                      "listed": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Every named outcome on the Polymarket event (used to check that the market lists every ballot candidate). Polymarket's unnamed placeholder slots ('Option A', 'Person B', a bare letter, 'Other') are removed."
                      },
                      "outcomes": {
                        "type": "array",
                        "maxItems": 4,
                        "items": {
                          "type": "object",
                          "required": [
                            "name",
                            "prob"
                          ],
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "prob": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1
                            }
                          }
                        }
                      },
                      "fetchedAt": {
                        "type": "string",
                        "format": "date-time"
                      }
                    }
                  }
                }
              }
            }
          },
          "generatedAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Ballot": {
        "type": "object",
        "required": [
          "zip",
          "state",
          "place",
          "electionDate",
          "districts",
          "races",
          "measures"
        ],
        "properties": {
          "zip": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "TX",
              "CA",
              "NY"
            ]
          },
          "place": {
            "type": "string"
          },
          "county": {
            "type": "string"
          },
          "counties": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "electionDate": {
            "type": "string",
            "format": "date"
          },
          "districts": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "label"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "note": {
                  "type": "string"
                }
              }
            }
          },
          "districtSource": {
            "$ref": "#/components/schemas/Source"
          },
          "splitWarning": {
            "type": [
              "string",
              "null"
            ]
          },
          "races": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Race"
            }
          },
          "measures": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "title",
                "source"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "summary": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                },
                "source": {
                  "type": "string"
                }
              }
            }
          },
          "problems": {
            "type": "array",
            "description": "Local Census figures.",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                },
                "year": {
                  "type": "string"
                },
                "source": {
                  "$ref": "#/components/schemas/Source"
                }
              }
            }
          },
          "verify": {
            "type": "object",
            "properties": {
              "label": {
                "type": "string"
              },
              "url": {
                "type": "string"
              }
            }
          },
          "cached": {
            "type": "boolean"
          }
        }
      },
      "Race": {
        "type": "object",
        "required": [
          "id",
          "title",
          "level",
          "office",
          "candidates",
          "source"
        ],
        "properties": {
          "id": {
            "type": "string",
            "examples": [
              "tx-35",
              "tx-governor"
            ]
          },
          "title": {
            "type": "string"
          },
          "level": {
            "type": "string",
            "enum": [
              "federal",
              "state",
              "county",
              "local",
              "measure"
            ]
          },
          "office": {
            "type": "string",
            "description": "What the office controls, in plain words."
          },
          "candidates": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Candidate"
            }
          },
          "source": {
            "type": "string"
          },
          "judicialNote": {
            "type": "string",
            "description": "Present on every judicial race: judicial candidates' positions on these issues aren't public."
          },
          "judicialNoteSource": {
            "type": "object",
            "description": "Present with judicialNote: the state's judicial conduct rule behind it.",
            "properties": {
              "url": {
                "type": "string",
                "format": "uri"
              },
              "label": {
                "type": "string"
              }
            }
          },
          "appliesNote": {
            "type": "string",
            "description": "Who this race applies to (district splits) plus where that comes from."
          },
          "splitNote": {
            "type": "string",
            "description": "Present when the ZIP is split between districts: the split text alone."
          },
          "sourceNote": {
            "type": "string",
            "description": "Present when a research note backs appliesNote: that source text alone."
          }
        }
      },
      "Candidate": {
        "type": "object",
        "required": [
          "name",
          "party",
          "incumbent"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "party": {
            "type": [
              "string",
              "null"
            ],
            "description": "As listed on the ballot."
          },
          "incumbent": {
            "oneOf": [
              {
                "type": "boolean"
              },
              {
                "const": "unsure"
              }
            ]
          },
          "ballotpedia": {
            "type": [
              "string",
              "null"
            ]
          },
          "officialSite": {
            "type": [
              "string",
              "null"
            ]
          },
          "positions": {
            "type": "array",
            "description": "Published, sourced stances only (exact text plus source). form: vote (roll-call record), quote (the candidate's own words), or summary (Ballotpedia text, not a quote). Judicial candidates have none.",
            "items": {
              "type": "object",
              "properties": {
                "issue": {
                  "type": "string"
                },
                "text": {
                  "type": "string"
                },
                "form": {
                  "enum": [
                    "vote",
                    "quote",
                    "summary"
                  ]
                },
                "year": {
                  "type": [
                    "string",
                    "integer"
                  ]
                },
                "source": {
                  "$ref": "#/components/schemas/Source"
                }
              }
            }
          },
          "photo": {
            "type": [
              "object",
              "null"
            ],
            "description": "Portrait shown on the site, or null (initials). Race mode (default) shows photos only when every candidate in the race has one. Never generated, never a news photo.",
            "properties": {
              "url": {
                "type": "string",
                "description": "Self-hosted /portraits/… path, or the candidate's own campaign/official image when hotlinked is true."
              },
              "credit": {
                "type": "string",
                "description": "\"Photo: {attribution}\" as displayed."
              },
              "attribution": {
                "type": "string",
                "description": "Full attribution text (author plus license when the source gives one)."
              },
              "author": {
                "type": "string",
                "description": "Author or owner only, without license text."
              },
              "license": {
                "type": "string",
                "description": "License or use basis, e.g. \"CC BY 2.0\", \"Public domain\", or a campaign's own public photo."
              },
              "page": {
                "type": "string",
                "format": "uri",
                "description": "Source page the credit links to."
              },
              "hotlinked": {
                "type": "boolean",
                "description": "True when the image loads from the candidate's own site rather than ours."
              },
              "focus": {
                "type": "array",
                "description": "[x, y, scale] crop focus for a square tile.",
                "items": {
                  "type": "number"
                }
              },
              "mate": {
                "type": "object",
                "description": "Running mate's photo on a ticket (same fields plus name)."
              }
            }
          },
          "causes": {
            "type": "array",
            "description": "Issues the candidate raises in their own campaign themes.",
            "items": {
              "type": "object"
            }
          },
          "money": {
            "type": "object",
            "description": "Campaign money from FEC filings (federal races)."
          }
        }
      }
    }
  }
}