Crosby News Health API

openapi: 3.2.0
info:
  title: crosbynews.com Health API
  version: 1.7.0
  description: 'Crosby, Texas community data: current conditions, hourly and 7-day forecast, active alerts, the EPA UV index, and a measured air-quality index (EPA/AirNow monitors, with an Open-Meteo modeled fallback) from the U.S. National Weather Service, EPA/AirNow, and Open-Meteo; river/bayou flood levels; the Atlantic tropical outlook; the Houston Health Department''s measured daily pollen and mold count; the Harris County burn-ban status from the Texas A&M Forest Service; road incidents and lane closures from Houston TranStar; recent local news headlines; and the Crosby ISD school calendar. Public, no authentication.'
  contact:
    url: https://crosbynews.com/
  license:
    name: Public domain (NWS source data)
    url: https://www.weather.gov/disclaimer
servers:
- url: https://crosbynews.com
security: []
tags:
- name: Health
paths:
  /api/health:
    get:
      operationId: getHealth
      summary: Site liveness, per-feed refresh attempts, and when the data last changed
      description: 'Three facts and nothing else: the site is live (this response proves it), when each feed last TRIED to fetch new data and whether that worked, and when the data shown on the pages actually changed. Reads one cached record and never touches an upstream, so polling it generates no upstream load. **Always `200`** — whether a timestamp is recent enough is the caller''s judgment, not this endpoint''s.'
      responses:
        '200':
          description: The report. Always 200 while the Worker is answering.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'
      tags:
      - Health
components:
  schemas:
    Health:
      type: object
      description: Site liveness plus, per feed, when it last tried to fetch and when its data last changed. EVERY timestamp is a human-readable US Central stamp, not ISO 8601 — "Friday, Aug 7, 2026, 11:20:35 AM CDT". The zone abbreviation resolves CST/CDT from the instant itself. null means no record rather than an unknown time. Each stamp is paired with an `hoursSince*` number, computed from the exact stored instant, so elapsed time can be thresholded without parsing the human date.
      properties:
        site:
          type: string
          description: Always "live" — reaching this response IS the liveness check.
        checkedAt:
          type: string
          description: When this report was generated. Never cached (`no-store`).
        cronLastRun:
          type:
          - string
          - 'null'
          description: When the refresh loop last completed a tick. null until the first tick after deploy.
        hoursSinceCronRun:
          type:
          - number
          - 'null'
          description: Elapsed hours since that tick, to one decimal. The cron runs every 15 minutes, so well past 0.25 means the refresh loop itself has stopped — a failure no per-feed field would show, since they would all sit still together.
        note:
          type: string
          description: Fixed guidance on reading `hoursSinceChange`, not a status field — its value never varies. A large gap is a fault only when the upstream should have moved; a quiet tropics basin or a weekend with no pollen count correctly holds still.
        feeds:
          type: object
          description: One entry per cached feed, keyed by name.
          additionalProperties:
            $ref: '#/components/schemas/HealthFeed'
        error:
          type: string
          description: Present only when the refresh record itself could not be read, e.g. the KV binding is missing. The response is still 200.
      required:
      - site
      - checkedAt
      - feeds
    HealthFeed:
      type: object
      properties:
        lastAttempt:
          type:
          - string
          - 'null'
          description: When this feed last TRIED to fetch new data. A throttled tick that was not due is not an attempt and does not move this. null for `news`, which a routine writes out-of-band, and until the first cron tick after deploy.
        hoursSinceAttempt:
          type:
          - number
          - 'null'
          description: Elapsed hours since that attempt, to one decimal. null when no attempt has been recorded.
        ok:
          type:
          - boolean
          - 'null'
          description: Whether that attempt succeeded. null when no attempt has been recorded.
        error:
          type: string
          description: 'Present only when the last attempt failed: the upstream error.'
        dataChangedAt:
          type:
          - string
          - 'null'
          description: When the cached content itself last CHANGED — not when it was last rewritten. A refresh that succeeds and re-stores identical data does not move this, which is how a feed serving frozen content becomes visible.
        hoursSinceChange:
          type:
          - number
          - 'null'
          description: 'Elapsed hours since the content changed, to one decimal. Read against hoursSinceAttempt: a feed refreshing successfully while this climbs is serving frozen data. Judge the threshold per feed — hours for weather/water/traffic, a day for pollen, longer for calendar and a quiet tropics basin.'