Homeschool Fox

Homeschool Fox
Compliance API

Endpoint — citations

The provenance behind every state record. Returns the declared source URLs (from the YAML) plus the 5 most recent monitoring snapshots (from the DB) so integrators can show their users when each source page was last successfully fetched.

GET /api/v1/compliance/citations/:state_abbreviation

curl -H "Authorization: Bearer $TOKEN" https://homeschoolfox.com/api/v1/compliance/citations/CA

{
  "data": {
    "state_abbreviation": "CA",
    "state_name": "California",
    "source_urls": [
      { "name": "HSLDA", "url": "https://hslda.org/legal/california" },
      { "name": "California Department of Education", "url": "https://www.cde.ca.gov/sp/ps/homeschool.asp" }
    ],
    "recent_snapshots": [
      {
        "url": "https://www.cde.ca.gov/sp/ps/homeschool.asp",
        "fetched_at": "2026-05-10T03:00:00Z",
        "content_hash": "9e7a4b...",
        "successful": true
      },
      ...
    ]
  },
  "meta": { "api_version": "v1" }
}

Why two layers

  • source_urls is curated editorial content — the canonical "where did this rule come from" list, edited via PR in the YAML.
  • recent_snapshots is automated: a weekly background job hashes the DOE pages we monitor for material changes. Their presence here lets your UI say things like "official source last fetched 2 days ago" without you having to run your own monitor.

A snapshot with successful: false indicates a fetch error (timeout, 5xx, etc.) — the URL is still tracked but we haven't been able to read it on the latest run.