Knowledge API Documentation

1. Overview

The Knowledge system provides machine-readable JSON pages for U.S. electricity rates, state metrics, rankings, and methodologies. Use the search-index for discovery; use entity pages for details. All pages include meta.freshness, meta.provenance, and meta.qualityScore.

2. LLM Ingestion Starter Pack

Recommended ingestion sequence for LLM tools. Follow this order for optimal discovery.

1. /knowledge/search-index.json— Primary discovery surface with tokens, excerpts, quality, freshness.Copy
2. /knowledge/contract.json— Schema contract and required fields.Copy
3. /knowledge/schema-map.json— Field grouping and entity patterns.Copy
4. /knowledge/provenance.json— Source metadata for citations.Copy
5. /knowledge/methodology/index.json— Methodology versions and relationships.Copy
6. /knowledge/rankings/index.json— Rankings catalog and methodology references.Copy
7. /knowledge/compare/states.json— Compact state comparison matrix.Copy
8. /knowledge/bundles/index.json— Offline ingestion manifests.Copy

Prefer canonical human pages for display; use JSON pages for structured ingestion. Use bundles for batch download when needed.

3. Entry points

Canonical list: public-endpoints.json

4. Entity types and URL patterns

• national: /knowledge/national.json
• state: /knowledge/state/{slug}.json
• methodology: /knowledge/methodology/{id}.json
• rankings: /knowledge/rankings/{id}.json
• vertical: /knowledge/vertical/{id}.json
• compare: /knowledge/compare/states.json

5. Provenance + citations

Every knowledge page includes meta.provenance (sources) and meta.citations. Field-level provenance is in meta.fieldProvenance. The global catalog is at /knowledge/provenance.json.

6. Methodologies and versions

Methodology definitions and versions are in the methodology index at /knowledge/methodology/index.json. Each methodology has id, version, and relatedDerivedFields.

7. Snapshots/history

Snapshot support is enabled. History index: /knowledge/history/index.json · Bundles: /knowledge/history/bundles/index.json

8. Bundles (offline ingestion)

Bundles index: /knowledge/bundles/index.json. Each bundle has a manifestUrl pointing to a list of JSON files for offline ingestion.

9. Release Snapshot

Pinned endpoints and integrity hash. See release.json for full details.

• releaseId: knowledge-v1-v2
• sourceVersion: v2
• contractVersion: 1.0.0
• manifestHash: e263e079a087d17da7faf83d8a82bad1412bbce40df74e01eeeb6f02ff6b1d91

10. System Capabilities

Build-time introspection. See capabilities.json for full details.

• historySnapshots: true
• bundles: true
• integrityManifest: true
• offersEnabled: false

11. Stability/verification notes

All knowledge artifacts are build-generated and deterministic. Index includes integritySignature and registryHash for verification. Page integrity uses contentHash (SHA-256). Regression guard: /knowledge/regression.json.

12. Release mode

Run RELEASE_MODE=1 npm run knowledge:check to enforce strict pre-launch checks. Release mode validates required artifacts (release.json, capabilities.json, public-endpoints.json, integrity manifest, search-index, index, contract), llms.txt coverage, and registry wiring.

Disclaimers