GovTech Provider API Documentation
The Aigistry GovTech Provider API allows approved GovTech platform providers to enroll verified government authorities, classify Authority Records by authority type, and submit approved records into the National AI Feed.
Provider-Enabled Participation Policy
National AI Feed participation is provider-enabled. Government agencies participate through approved GovTech Provider integrations and verified Authority Records, not through direct Aigistry publishing accounts or direct operational hookups.
Authority Records include a required authority_type field used to classify the government authority associated with the record.
Base URL
All GovTech Provider API requests use the following base URL.
Authentication
Approved providers receive a long-lived, provider-scoped API Key. It is sent directly in the X-API-Key request header on every integration request — never in the request body. There is no token-exchange step and no expiring session token for machine calls. The key is shown in full exactly once, at creation, in your Provider dashboard.
API Keys are provider-scoped. Every authenticated request must include a valid, Active API Key. Government agencies do not receive direct Aigistry publishing accounts or credentials. API Keys are created and managed from your Provider dashboard, not through this integration API itself.
Step 1. Enroll a Client Agency
This endpoint creates a provider-scoped Authority Record for a government publishing authority. The authority_type field is required and identifies the authority classification associated with the record. Enrollment is fully automatic for any Active Provider — there is no separate manual or domain-based verification step before an Authority Record becomes Active. Each Authority Record is owned outright by the enrolling Provider, with its own name, type, website, and location fields — never shared with or affected by any other Provider.
The required authority_type value must be one of: Federal, State, County, City, Town, Village, Public School District, Public College, Public University, Special District, or Other.
Example Request — City Authority
Example Success Response
Example Request — State Authority
Step 2. Review and Edit Provider Authorities
Approved providers may retrieve their own Authority Records at any time. Each Authority Record carries its own name, type, website, and location fields directly — there is no separate lookup or join involved.
Returns all Authority Records associated with the authenticated Provider.
Edits any subset of authority_name, authority_type, website, city, state_province, country on an Authority Record you own. Because each Authority Record is fully owned by the Provider that created it, an edit can never affect another Provider’s record — even if two Providers enrolled the same agency by name.
Providers remain responsible for customer-facing reporting, dashboards, and account management inside their own systems. Aigistry’s endpoints provide the underlying data and edit capability, not a hosted dashboard.
Step 3. Publish a Verified Record
Publishing uses the same X-API-Key header as every other request — not a separate authority-specific credential. Providers submit a title, body, an Authority Record id, and optional source/video URLs. Aigistry attaches verified authority metadata from the Authority Record itself; providers do not resend organization or jurisdiction details on each publish call.
An optional idempotency_key may also be included — see “Idempotent Publishing” below for why this matters once you’re integrating for production use, not just testing.
Example Success Response
Signing happens on the next feed-generation run, not at submission time. A successful publish.php response means the record has been validated and accepted — publication_hash and signature are empty strings until the next scheduled feed-generation cycle signs and appends the record to the public National AI Feed. Publications are immutable once submitted; corrections are made by publishing a new record, not editing an existing one.
Idempotent Publishing
Because Publications are immutable once submitted, a naive retry after a network timeout or dropped connection could otherwise create a permanent duplicate record — one that can never be edited away the way a mistaken Authority Record could be corrected. The optional idempotency_key field on publish.php solves this.
Idempotency keys are scoped per Provider, not global. Two different Providers may safely use the same key string with no conflict at all — only a repeated key from the same Provider is treated as a retry of a previous request.
Submitting the same idempotency_key a second time returns the original Publication unchanged, with idempotent_replay: true — no new record is created, and nothing about the original submission changes.
idempotency_key is entirely optional. If omitted, publish.php does not perform key-based replay detection — but the automatic duplicate-content safeguard described below still applies, and may return an existing Publication if identical content is resubmitted by the same Provider within the detection window. Omitting the key does not disable Aigistry’s protection against accidental duplicates; it only means that protection is based on matching content rather than a key you control.
Automatic Safeguards
idempotency_key is a tool a Provider controls. The two protections below run automatically on every publish.php call, regardless of whether a key is sent — they protect the feed even when an integration doesn’t help itself.
Duplicate Content Detection
If the same Provider submits the same Authority Record, title, and body again within 10 minutes — with no idempotency_key, or a different one each time — Aigistry recognizes the match and returns the original Publication instead of creating a new one. This is deliberately a short window: it catches accidental rapid resubmission (a retry-loop bug, a double-click) without blocking a genuinely intentional republish of the same content later, such as a city re-announcing “road closure still in effect” a week on.
Two calls with identical Authority Record, title, and body — the second returns the original record with duplicate_content_detected: true, matching id and submitted_at from the first.
Rate Limiting
publish.php is limited to 30 requests per minute, per Provider, per mode. Test Mode and Live Mode are tracked separately — load-testing a sandbox integration never consumes a Provider’s live rate budget, and vice versa. This is a hard cap that applies regardless of content, so it stops a runaway loop or a burst of malformed retries even when every individual request would otherwise be valid.
The 31st request within a rolling one-minute window returns a rate-limit error instead of being processed.
Neither safeguard requires any change to how you call publish.php — both run automatically, on every request, in addition to idempotency_key if you choose to send one. A well-behaved integration publishing at normal volume should never encounter either limit.
Authority Records
Authority Records are the verified operating objects that connect a Provider, an authority-type classification, publishing eligibility, and status. Each Authority Record is fully self-contained and owned by a single Provider.
Authority Identity
Each Authority Record has a numeric id. Publishing requests reference this id directly.
Authority Type
Federal, State, County, City, Town, Village, Public School District, Public College, Public University, Special District, or Other.
Status
Authority Records are either Active or Suspended. Only Active Authority Records can accept new Publications.
Publishing Pipeline
Accepted Publications are validated at submission time and stored immediately as Active. Cryptographic signing happens separately, on the next scheduled National AI Feed generation run.
Cryptographic Provenance & Feed Integrity
Verified Authority Record publications submitted through the GovTech Provider API receive cryptographic proof fields once signed during feed generation. These proof fields provide an additional integrity layer for machine-readable government communications.
Record Hashing
Aigistry generates a SHA-256 hash of the finalized record content — a tamper-evident fingerprint, populated at feed-generation time.
Digital Signatures
Aigistry signs the record hash using Ed25519. The signature and a reference to the signing key are attached to the record.
Independent Verification
Any downstream system holding Aigistry’s published public key may independently validate a signed record against its hash.
Example Proof Fields (as they appear in the live National AI Feed)
These fields are populated on every signed National AI Feed record, after the next feed-generation run following submission.
Operational Safeguards
Authentication Enforcement
Every request requires a valid, Active API Key sent via X-API-Key. Missing, invalid, or disabled keys are rejected before any data is read or written.
Authority Status Enforcement
Publishing against a Suspended Authority Record is rejected. Only Active Authority Records can receive new Publications.
Single Feed Architecture
All accepted Publications, from every Provider, flow into one authoritative public National AI Feed.
Authority Lifecycle
| Status | Description |
|---|---|
| Active | Authority Record can receive new Publications. |
| Suspended | New Publications against this Authority Record are rejected. Historical Publications and attribution remain intact and unaffected. |
Suspend an Authority Record
No approval required — Providers control suspension of their own records directly, e.g. when a client agency ends its engagement. No request body needed.
Reactivate an Authority Record
Restores publishing capability immediately, without re-enrollment.
Recommended Integration Workflow
- Store your API Key securely. It’s shown in full only once, at creation, in your Provider dashboard.
- Enroll the Authority. Enroll each government authority once, during provider onboarding or first use.
- Store the Authority Record id. Reference this id directly on every future publish call.
- Submit records. Send a title, body, and the Authority Record id to
publish.php— include anidempotency_keyfor production traffic. - Track status. Use the Authority Records and Publications endpoints for eligibility and history visibility.
- Maintain your own account layer. Continue managing the agency relationship, support experience, dashboards, and reporting inside your own platform.
Why Providers Integrate
GovTech platforms already manage official government publishing workflows. Aigistry extends those existing environments into a structured attribution layer designed for AI interpretation environments. The operational objective is not to replace existing GovTech publishing systems, but to extend authoritative government publishing workflows into downstream machine-readable attribution infrastructure.
Integration Assets
Approved GovTech Providers integrating with the Aigistry Provider API may use the official National AI Feed publishing control and official National AI Feed symbol within publishing workflows, administrative interfaces, dashboards, documentation, websites, and implementation materials. Use of these assets identifies National AI Feed publishing capability and does not imply government endorsement, certification, or affiliation.
National AI Feed Publishing Control
The official button/control identifying National AI Feed publishing capability, for use in administrative interfaces, dashboards, and publishing workflows.
National AI Feed Symbol
The official National AI Feed symbol, for use in documentation, websites, and implementation materials.
