Aigistry Provider APIs
Technical reference for approved GovTech Providers integrating the National AI Feed into existing government communications platforms.
The Provider API supports deployment across federal, state, county, city, town, village, public school district, public college, public university, special district, and other approved government authorities through the same Provider integration architecture.
Developer Resources
The OpenAPI specification is the machine-readable source of truth for this API — every endpoint, request body, response schema, and authentication scheme documented in one file.
The OpenAPI file is published at https://aigistry.com/openapi.json. It reflects the live, deployed API exactly — every request/response example on this page is drawn from the same source.
Participation Model
Provider-Enabled Access
Government agencies do not authenticate directly with Aigistry. Participation occurs through approved GovTech Provider integrations and verified Authority Records.
Consistent Authority Model
Federal, State, County, City, Town, Village, Public School District, Public College, Public University, Special District, and Other approved authorities use the same Provider API architecture.
Provider-Managed Integration
Approved Providers manage Authority Records and publishing workflows for the government organizations they support while Aigistry operates the downstream National AI Feed infrastructure.
Publishing to the National AI Feed is free for approved GovTech Providers and the government authorities they represent — there is no per-record fee, subscription, or billing relationship involved in using this API.
API Status
Checked live against the running system each time this page loads — not a static claim.
Provider API
Status: Checking…
National AI Feed
Status: Checking…
Last generated: —
Records in feed: —
Base URL
All provider API requests use the following base URL.
Request Format
Provider API requests use JSON request bodies and return JSON responses over HTTPS. Every response includes a top-level success boolean.
Authentication Model
API Key
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 dashboard.
API Keys are provider-scoped. Every authenticated integration 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 the integration API itself.
Standard Publishing Workflow
- Provider logs into their dashboard and generates an API Key.
- Provider calls
authority-records.phpwith the client agency’sauthority_nameandauthority_typeto create an Authority Record — sending the API Key directly, no separate authentication call. authority_typemust be one of:Federal,State,County,City,Town,Village,Public School District,Public College,Public University,Special District,Other.- Provider calls
publish.phpwith the resultingauthority_record_id, a title, and body content. - Aigistry validates the API Key and the Authority Record’s status before accepting the submission.
- Accepted Publications are cryptographically signed on the next feed-generation run and become part of the National AI Feed.
API Groups
Provider Publishing API
Used to create Authority Records and submit records for National AI Feed processing.
GET / POST authority-records.phpGET / PUT authority-records.php?id={id}POST authority-records.php?id={id}&action=suspendPOST authority-records.php?id={id}&action=reactivatePOST publish.phpGET publications.php
Provider Management API
Used for account profile, contact info, address, and API Key management. Contact and address fields are managed through the same account.php endpoint, not separate resources.
GET / PUT account.phpGET / POST / DELETE api-keys.php
Core Endpoint Examples
Create (enroll) a new Authority Record for a client agency.
Submit a record for the next National AI Feed generation. idempotency_key is optional but recommended — see “Idempotent Publishing” below.
Edit an Authority Record you own — any subset of authority_name, authority_type, website, city, state_province, country, provider_authority_id.
Suspend one of your own Authority Records — for example, when your client agency ends their engagement with you. No request body needed.
List Publications submitted by your Provider, optionally filtered by Authority Record.
Idempotent Publishing
publish.php accepts an optional idempotency_key field. If a network timeout or connection drop happens after Aigistry accepts a Publication but before your integration receives the response, a naive retry could otherwise create a second, permanent record — Publications are immutable once submitted, so a duplicate cannot be edited away afterward the way a mistaken Authority Record could be corrected.
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 Aigistry’s automatic duplicate-content safeguard still applies: identical content resubmitted by the same Provider within a short detection window returns the existing Publication rather than creating a new one. 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.
Operational Guardrails
Provider-Scoped Access
API Keys resolve to a single Provider. Requests return or modify only records associated with the authenticated Provider.
Provider-Owned Authority Records
Authority Records represent your relationship with your own client agency. You may edit their details, or suspend or reactivate them, at any time; Aigistry does not gate these decisions.
Historical Feed Integrity
Provider APIs cannot rewrite historical National AI Feed records, remove published records, or alter cryptographic proof fields. Corrections are made by publishing a new record.
Error Responses
API error responses use a consistent structure: success is false and error is a human-readable message.
Authentication
Missing X-API-Key header.(401)Invalid or disabled API key.(401)Provider account is not active.(403)
Authority & Publication
Authority Record not found.(404)Authority Record is not Active.(403)Missing required field: {field}(400)
Account Management
API key not found.(404)Invalid contact_email format.(422)No updatable fields provided.(400)
Real-World Integration Examples
Publish a State Emergency Update
A GovTech Provider can submit public emergency management information on behalf of an active, verified State Authority Record.
Publish a Road Closure Notice
A municipal website provider can submit a road closure notice on behalf of an active, verified City Authority Record.
Offboard a Client Agency
When a Provider’s client agency ends its engagement, the Provider suspends the corresponding Authority Record directly — no Aigistry approval required.