How it works
GovTech Providers put records into the feed. The feed signs each one and chains it to the one before. AI Platforms read the feed in order and verify it.
Roles
| Role | Key | What it does |
|---|---|---|
| GovTech Provider | GovTech Provider key | A company that supplies technology to governments. Enrolls governments, publishes, revises and withdraws records for them, reads the state of its own publications. |
| AI Platform | AI Platform key | An AI company or service that uses official information. Reads the signed feed, downloads attached files, looks up authority records and the state of any publication. |
A government is the authority a record is attributed to. It is the subject of the feed, not a user of the API.
Access and keys
Access is by request to admin@aigistry.com. Once an account is approved, its members sign in to the dashboard at https://feed.aigistry.com/signin.html with a one-time link sent by email; the link works once and expires in 15 minutes. Keys are created in the dashboard, shown once, and labeled so they can be told apart. An account can hold up to 10 active keys, and a new key does not stop the others.
Send a key in the X-API-Key header, or as Authorization: Bearer. GovTech Provider keys start with naf_prov_ and AI Platform keys with naf_plat_. GET /v1/whoami returns the kind, name and label for a key.
Enrollment
Before publishing for a government, a GovTech Provider enrolls it with POST /v1/authority-records, one government or a batch of up to 500, and attests that it is authorized to publish for each one. The result is an authority record: one government enrolled by one GovTech Provider. Its id is used in every publication route.
Each government is matched to the loaded Census or NCES list (official_id_type census_pid6 or nces_leaid), or added as an unlisted government with an identifier the GovTech Provider supplies (other). Checks raise a flag on the enrollment (state_mismatch, level_mismatch, name_mismatch, unlisted, non_standard_agency) and never block it. AI Platforms see the flag, the attestation and the sampling state in the authority record lookup.
Ending an enrollment (DELETE /v1/authority-records/{id}) writes a signed status entry and deletes nothing. Enrolling the government again makes the record active and writes a signed reinstatement.
Publishing
A GovTech Provider publishes with POST /v1/authority-records/{id}/publications and a body of external_id, title and body, with optional agency, source_url, published_at and up to 5 attachments. The external_id is the GovTech Provider's own identifier for the publication (1 to 128 printable characters). A new external_id creates the publication as revision 1. Posting an existing external_id appends a revision that supersedes the previous one.
Files (PDF or Word .docx, up to 20 MB) are uploaded first to POST /v1/authority-records/{id}/files, and their ids are listed in the publication's attachments. Each file is bound to its authority record and can be attached once. A GovTech Provider withdraws a publication with DELETE on its path; the withdrawal is a signed removal entry.
Signing and order
Every entry is signed on arrival with Ed25519 and appended to a single ordered sequence (seq). Each entry carries the seq and record_hash of the entry before it (prev_seq, prev_hash), so a change, insertion or removal anywhere in the sequence shows. record_hash is the SHA-256 of the entry's canonical JSON, and the signature covers that hash. Each feed page ends with a feed_head, a statement of the newest entry signed at the time of the request.
The exact canonical form and every check are in the verification rules.
Standing
A change of standing is itself a signed entry in the same feed and chain. It has a scope and an event.
| Scope | Events |
|---|---|
| GovTech Provider | suspended, reinstated, revoked, revocation_lifted |
| authority_record | suspended, reinstated, ended, revoked, revocation_lifted |
| publication | revoked, revocation_lifted |
The current state of a publication (current, withdrawn or revoked) is derived from the signed entries. GET /v1/authority-records/{id}/publications/{external_id} returns the same answer, and the reference verifiers compute it from the feed.
Reading
An AI Platform reads GET /v1/feed?after=N&limit=M, which returns the entries with seq greater than N in order, with next_after, has_more and a signed feed_head. It keeps reading while has_more is true. A read can be limited to one authority record, one GovTech Provider or one government. For AI Platforms has the reading loop.