The GII public interface treats explainability as an API property: every score endpoint exposes links to its evidence, estimates, sources, and methodology version, so a consumer can reconstruct any published value. The resource model below is normative from methodology v1.1.1; the live service ships with the pilot.
Access#
The descriptive endpoints are keyless — what the index measures, where it looks, the connector registry, the record types, and the public challenge process. The compute endpoints require an API key. The split and the reasoning are on API access; the short version is that a reviewer who cannot check where the index looks, without paying, cannot review it.
curl -H "Authorization: Bearer <key>" \
https://gii.apiautomations.com/api/v1/seriesAn x-api-key header works equally. Without a key a metered endpoint returns 401 with a WWW-Authenticate header; an expired key returns 402 and a renewal link. The machine-readable contract in openapi.yaml marks which operations need one, and a build check holds that marking to the same endpoint map the server enforces — so a generated client cannot be surprised in production.
Live compute API#
A working subset is already live: the reference implementations (@gii/core, @gii/lineage, @gii/codebook) run behind stateless endpoints. The compute endpoints take a record you supply and return the full explainable result — the same code the sandbox and the gii CLI use. They compute on supplied inputs only and publish no scores.
| Method | Endpoint | Returns |
|---|---|---|
| GET | /api/v1 | Endpoint catalog for the live compute API |
| GET | /api/v1/methodology | Machine-readable methodology reference: versions, weights, thresholds, evidence ladder, maturity states |
| GET | /api/v1/codebook | Outcome codebook (optional ?domain= filter) |
| GET | /api/v1/sources | Source inventory & profiles: hierarchy, retrieval, coverage; ?origin=/?domain=/?tier= |
| GET | /api/v1/relational | Relational table catalog + emitted PostgreSQL DDL |
| GET | /api/v1/connectors | Source-connector registry: pagination, auth env-var names, endpoints |
| GET | /api/v1/conformance | Whitepaper invariants held against generated adversarial inputs; ?seed=&cases= |
| GET | /api/v1/traceability | Every whitepaper mapped to code, tests, and status — including what is partial or absent |
| GET | /api/v1/assurance | Metamorphic relations and the historical defect record — the checks on the checks. The seeded-fault audit is CLI-only by design |
| GET | /api/v1/intake | The fixture-driven multi-source intake haul: payloads to a populated Decision Event Registry; ?at= (→) |
| GET | /api/v1/rehearsal | The synthetic pilot dress rehearsal: a fictional corpus through the whole pipeline; ?cases=&at= |
| GET | /api/v1/downloads | Bulk data products for research reproducibility |
| GET | /api/v1/downloads/{name} | One bulk data product as an attachment (JSON/CSV/SQL) |
| GET | /api/v1/governance | Review roles, publication eligibility, correction policy, and challenge process |
| GET | /api/v1/dossiers | Index of illustrative beta decision dossiers |
| GET | /api/v1/dossiers/{id} | One beta decision dossier in the order |
| GET | /api/v1/schema/{name} | A published JSON Schema (all eighteen): decision-impact-record · policy-lineage-graph · outcome-codebook · decision-event-record · source-adapter-health · sensitivity-report · release-package · candidate-frame · challenge-record · correction-record · source-profile · relational-schema · calibration-input · series-frame · connector-spec · conformance-report · rehearsal-report · intake-report |
| POST | /api/v1/score | Compute the full scorecard for a Decision Impact Record |
| POST | /api/v1/sensitivity | Plausible range across alternative specifications |
| POST | /api/v1/release | Reproducible, hash-timestamped release package |
| POST | /api/v1/validate | Quality controls + codebook preregistration |
| POST | /api/v1/lineage | Check a Policy Lineage Graph and derive roots, leaves, non-overlap factors |
| POST | /api/v1/challenges | Intake a structured public challenge; returns a tracking ID |
| POST | /api/v1/calibration | Inter-rater reliability: grade reviewer ratings vs. the pilot thresholds |
| POST | /api/v1/series | Assemble national/institutional/domain impact-pressure series |
Planned resource model#
| Resource | Returns |
|---|---|
| /decisions | Decision Impact Records with filters for origin, institution, domain, status, maturity, geography, and time |
| /lineages | Typed policy-lineage graphs for a decision or family |
| /outcomes | Outcome definitions and observed series with vintages |
| /estimates | Causal estimates with design, uncertainty, and diagnostics |
| /scores | Scorecard values with method and evidence links |
| /series | Institutional and national aggregate series with coverage and composition |
| /sources | Source registry with provenance and license metadata |
| /source-adapters | Adapter registry, versions, coverage, and health |
| /releases | Release packages, changelogs, and correction notices |
| /methodology | Versioned methods, weights, and thresholds as machine-readable references |
Response contract#
Versioned endpoints; explicit units, definitions, and vintages on every value; uncertainty and maturity fields wherever scores appear; stable pagination; and machine-readable deprecation notices. Nothing is served as a bare number: a score without its coverage, confidence, and maturity context is a misreading the API is designed to prevent.