Technical Architecture
This page describes what the National AI Feed actually does, end to end — how a Publication moves from a Provider’s platform to a cryptographically signed, publicly retrievable record, and what controls sit around that path. Every claim here reflects the current, deployed system.
Request Flow
A single Publication moves through the same fixed sequence every time, with no shortcuts and no exceptions for any Provider.
Signing happens on the next scheduled feed-generation run, not at the moment a Publication is accepted. A successful publish.php response confirms the record was validated and stored — not that it has been signed yet. This is a deliberate, documented asynchronous step, not a delay bug.
Security
Authentication and authorization controls apply identically to every Provider, on every request, with no exceptions carved out for convenience.
Authentication
Every machine-to-machine Provider API request requires a valid, Active, provider-scoped API Key sent via X-API-Key — missing, unknown, or disabled keys are rejected before any data is read or written, and the system fails closed by default. API Key management itself is the one exception, requiring an authenticated dashboard session instead of a key, since a Provider must be able to create their first key before any key exists.
Provider Isolation
Every query on every endpoint is scoped by the authenticated Provider’s own provider_id. A Provider can never read, edit, or reference another Provider’s Authority Records, Publications, or account data — enforced at the query level, not just the UI.
Rate Limiting
Publishing is capped at 30 requests per minute, per Provider, per mode (Test and Live tracked separately). A burst of traffic — accidental or otherwise — is stopped before it can reach the database validation layer, not caught after the fact.
Idempotent Publishing
Providers may attach an optional idempotency_key to prevent a network retry from creating a duplicate, permanent record. Reusing a key with genuinely different content is rejected outright — a stale replay is never silently returned in place of new content, and a mismatched reuse is never silently discarded either.
Automatic Duplicate Detection
Independent of any key a Provider sends, identical content submitted by the same Provider within a 10-minute window is recognized and returned as the original record, not duplicated — protecting the feed even when an integration doesn’t help itself.
Security Logging
Authentication failures — missing, unknown, or disabled credentials, inactive Provider accounts — are recorded separately from ordinary Provider activity, with a hashed credential fingerprint for pattern detection across repeated attempts, never the raw credential itself.
Safe Error Handling
A global handler catches any unexpected failure across the entire API, in addition to explicit handling on individual endpoints. The client always receives a generic, safe error message; full internal detail — file, line, exact cause — is captured separately for review, never exposed in the response.
Second-Factor Approval
Approving a new Provider requires a second confirmation step, sent to a fixed internal address rather than the requesting session. A compromised Operator session alone cannot grant a Provider publishing access — the approval only takes effect once that separate confirmation is completed. This currently covers Provider approval specifically, the single highest-consequence action in the system; other sensitive Operator actions rely on session authentication alone today.
Every publishing request is validated before it reaches the database: required fields, type and enum correctness, field-length limits matching the underlying schema, and format validation on optional URL fields — rejecting malformed input as early and cheaply as possible, not relying on the database itself as the validation layer.
Cryptographic Provenance
Every Publication that reaches the public feed carries independently verifiable proof of its origin and integrity.
Record Hashing
A SHA-256 hash is generated from the finalized record content at signing time — a tamper-evident fingerprint of exactly what was published.
Digital Signatures
Each record is signed using Ed25519. The signature and a reference to the signing key are attached directly to the record.
Independent Verification
Aigistry’s public key is published separately, structured to support multiple keys over time — each with its own key identifier, matched directly against the signing_key_id on every record. Any downstream system can validate a record’s signature against its hash without contacting Aigistry, and can continue verifying records signed under a retired key indefinitely.
Source Attribution
Every record preserves the issuing Authority Record’s identity, jurisdiction, and the original source_url it was published from — attribution travels with the record, not just the feed metadata.
The private signing key is file-permission-restricted (owner-only, non-listable directory) to the single account that performs signing. A documented rotation and revocation procedure exists, describing how a new key is introduced and an old key retired without invalidating any previously signed record.
Example Proof Fields (as they appear in the live National AI Feed)
Operations
Automated Feed Generation
A scheduled process runs every 5 minutes: signing newly accepted Publications, and rewriting the public feed file. The feed’s generated_at timestamp updates on every run, including runs with nothing new to sign — so a stalled or frozen timestamp is itself a visible signal, not silently hidden.
Immutable Publications
Publications cannot be edited or deleted once accepted. Corrections are made by publishing a new record, preserving the full, unaltered history of what was originally said.
Backups, Verified by Restoration
The production server takes automated daily snapshots, with a seven-day rolling retention window. A snapshot has been restored to a separate instance and confirmed to produce a fully functional copy — application code, database, and the feed-generation process itself all came back intact and running.
Isolated Test Environment
Every API Key is explicitly Test or Live. Test Mode data — Authority Records, Publications, account activity — is fully isolated from Live data: it is never signed and never appears in the public feed.
Live Status Visibility
A public status check reports real, current system state — API reachability and database connectivity, and whether the National AI Feed is actively regenerating on schedule or has silently stalled — checked fresh on every request, not a static claim.
Health Monitoring & Alerting
An automated check runs on a fixed schedule, independent of the feed-generation process itself, and sends a direct notification on a genuine health transition — going down, remaining down, or recovering — rather than requiring anyone to notice a problem by checking manually.
Integration
REST / JSON
All Provider API requests use JSON request bodies and return JSON responses over HTTPS, with a consistent success boolean on every response.
OpenAPI 3.0
The complete API surface is documented in a published OpenAPI 3.0 specification — the machine-readable source of truth for every endpoint, request, and response.
Sandbox Access
A Test Mode key can be generated directly from the Provider dashboard, with no separate approval step, for building and verifying an integration before touching live data.
Single Authentication Model
One long-lived, provider-scoped API Key, sent directly on every request. No token-exchange step, no expiring session to manage for machine-to-machine calls.
Versioning Policy
A published policy states what changes freely (new fields, new endpoints), what never changes without notice, and how a breaking change would be introduced and communicated if one is ever needed — established before the first integration, not written after something broke.