The live half of the source inventory: for every documented-API source, a declarative connector spec — base URL, endpoints, pagination style, and how a credential is injected, by environment-variable name only. No credential value exists anywhere in this repository. The runner retries with deterministic backoff, honors Retry-After, treats returned rate-limit headers as authoritative over any documented quota, caches immutable payloads, persists every raw page before parsing, and redacts credentials from every surfaced line.
19 specs rendered live from @gii/connectors · validation errors 0 · unconnected documented-API profiles none.
Connectors by credential class
What each source requires to answer — a name, never a value. Provisioning the named environment variables turns a spec live with no code change.
- Registration key737%
- No credential737%
- Token316%
- API key211%
19 connectors in total · The registry
Connector registry#
| Source | Pagination | Credential | Endpoints |
|---|---|---|---|
| congress-gov 5,000 requests/hour (api.data.gov key) (advisory) | offset | registration-key · $CONGRESS_GOV_API_KEY | bills, law ◆ |
| govinfo | cursor | registration-key · $GOVINFO_API_KEY | collections, package ◆ |
| federal-register no key; fair-use throttling (advisory) | page | no key | documents, document ◆ |
| ecfr | none | no key | structure, full ◆ |
| regulations-gov 1,000 requests/hour (api.data.gov key) (advisory) | page | api-key · $REGULATIONS_GOV_API_KEY | documents, docket |
| courtlistener 5,000 queries/day (free tier) (advisory) | cursor | token · $COURTLISTENER_API_TOKEN | opinions, dockets |
| bls 500 queries/day (registered v2) (advisory) | none | registration-key · $BLS_API_KEY | series |
| bea 100 requests & 100MB per minute (advisory) | none | registration-key · $BEA_API_KEY | data |
| census 500 queries/day without key (advisory) | none | registration-key · $CENSUS_API_KEY | dataset |
| treasury-fiscal-data | page | no key | dataset |
| usaspending | page | no key | awards |
| usitc-dataweb | none | token · $USITC_DATAWEB_TOKEN | trade |
| sec-edgar 10 requests/second (fair-access; declared User-Agent required) (advisory) | none | no key | submissions, companyconcept |
| cms | offset | no key | dataset-list, dataset-data |
| openfema | offset | no key | disaster-declarations |
| dol | offset | registration-key · $DOL_API_KEY | dataset |
| fred 120 requests/minute (advisory) | offset | api-key · $FRED_API_KEY | series-observations, series |
| eia | none | registration-key · $EIA_API_KEY | route-data |
| hud | none | token · $HUD_API_TOKEN | fair-market-rents, income-limits |
◆ immutable — cacheable by URL after first retrieval.
Walking demo#
The shipped federal-register spec, driven by the same runner a live transport would use — here against an in-memory transport at build time. Two pages; the second comes back short, so the bounded walk stops itself:
page 1: GET https://demo.invalid/api/v1/documents.json?per_page=3&page=1 → 200 in 1 attempt(s) page 2: GET https://demo.invalid/api/v1/documents.json?per_page=3&page=2 → 200 in 1 attempt(s)
Each page yields a retrieval record with the fields — retrieval time, URI, publisher, content type, checksum, schema/extraction version, license, transformation history, and last validation — and lands in the append-only raw-evidence store.
Going live#
Turning a spec live requires no code change: provision the environment variable each credentialed spec names (e.g. CONGRESS_GOV_API_KEY, REGULATIONS_GOV_API_KEY), and the same runner, retries, caching, and redaction apply. The contract suite runs against a local mock server, and the PEPI adapter remains the walking-skeleton example of the full ingestion boundary.
Seven of these sources need no credential, and four of them retrieve real data today — the Federal Register, OpenFEMA, the eCFR, and SEC EDGAR, checked against the live APIs rather than against fixtures. Three do not: two return a 404 on a path that has moved since the spec was written, and one takes its query in a request body, which this spec format cannot express.
Retrieving a source is not scoring one. Retrieval is plumbing; a published score is a claim, and the withhold rule stands between them. GII-US is pre-pilot and publishes no score about any real government decision.
Whether a source works is checked one request at a time, by a command that writes nothing: a probe reports the status, whether the payload matches the shape the spec describes, and — when it does not — which of ten failure classes it is and what to do about it. A wrong key, an unactivated key, a key without entitlement, a spent quota, and a moved endpoint are five different problems, and only some of them are the operator’s.
Machine-readable at GET /api/v1/connectors · gii connectors.