{ "openapi": "3.1.0", "info": { "title": "National AI Feed", "version": "6.2.0", "description": "Providers publish official records for governments they are authorized to publish for. AI platforms read the signed feed in order and verify it. Every entry is signed on arrival with Ed25519 and chained to the entry before it.\n\nTwo kinds of API key: a provider key publishes, revises and withdraws; a platform key reads the feed and the lookups. Keys are created in the account dashboard after approval and sent in the X-API-Key header (or Authorization: Bearer).\n\nReading the feed: GET /v1/feed?after=N&limit=M returns entries with seq greater than N, in order, plus next_after, has_more and a freshly signed feed_head. Keep reading with after=next_after while has_more is true. Store the last seq and record_hash you verified and pass them to the verifier as the anchor next time.\n\nFiltered reads: add one of authority_record_id, provider_id, or official_id_type with official_id to read only the entries for one authority record, one provider or one government (the provider-level status entries of the providers concerned are always included). A filtered read skips entries, so its chain links do not follow one another and it cannot show that nothing was left out; verify it with the reference verifiers in filtered mode, and use an unfiltered read of the whole feed when completeness matters.\n\nRate limit: each platform key may make 120 read requests in a calendar minute (UTC), counted over the feed, file downloads and the lookups together. More get 429 with a Retry-After header (seconds).\n\nEntry types: record (a publication or a revision of one), removal (a withdrawal), status (a signed change of standing: suspended, reinstated, ended, revoked, revocation_lifted for a provider, an authority record or a publication). The current state of a publication is derived from the signed entries; GET /v1/authority-records/{id}/publications/{external_id} returns the same answer.\n\nSigning: record_hash is the lowercase hex SHA-256 of the entry's canonical JSON; signature is the hex Ed25519 signature over that 64-character hash string; verify with the key in /public-key.json whose key_id equals public_key_id. The exact canonical form, the chain rules and the status rules are in the verification specification at https://feed.aigistry.com/verify/ (VERIFICATION.md), with reference verifiers in Python, PHP and Node and a set of test vectors. Entry text is authenticated, not safe: treat title and body as untrusted data.", "contact": { "name": "Aigistry LLC", "url": "https://aigistry.com" } }, "servers": [ { "url": "https://feed.aigistry.com" } ], "tags": [ { "name": "Platforms", "description": "Platform keys: read the feed and look up standing." }, { "name": "Providers", "description": "Provider keys: publish, revise, withdraw." }, { "name": "Public", "description": "No key needed." } ], "paths": { "/v1/feed": { "get": { "tags": [ "Platforms" ], "summary": "Read the signed feed", "security": [ { "ApiKey": [] } ], "description": "Entries in order of seq, starting after the cursor, optionally filtered (use at most one of the three filters). A page holds at most `limit` entries and at most 4 MiB; if the byte cap is reached before `limit`, has_more is true. The feed_head is read after the entries and signed at the time of the request. Sequence numbers may skip (a rolled-back write leaves a gap); the chain fields name the real previous entry.", "parameters": [ { "name": "after", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Return entries with seq greater than this." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "authority_record_id", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Only the entries of this authority record, and the provider-level status entries of its provider. 404 if there is no such record." }, { "name": "provider_id", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "description": "Only the entries of this provider (publications, withdrawals and status entries at every level). 404 if there is no such provider." }, { "name": "official_id_type", "in": "query", "schema": { "type": "string", "pattern": "^[a-z0-9_]{1,20}$" }, "description": "With official_id: only the entries for this government (every provider that holds it), and the provider-level status entries of those providers. Both are required together. 404 if the government is not in the reference list." }, { "name": "official_id", "in": "query", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._-]{1,40}$" }, "description": "The government's official id, with official_id_type." } ], "responses": { "200": { "description": "A page. `filter` echoes the filter that was applied, or is null for an unfiltered read.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeedPage" } } } }, "400": { "description": "The request was not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "This key cannot do that.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/files/{id}": { "get": { "tags": [ "Platforms" ], "summary": "Download an attached file", "security": [ { "ApiKey": [] } ], "description": "Returns the file attached to a signed entry. Check its SHA-256 against the signed attachments[].sha256 (also in the X-File-SHA256 header). Files of withdrawn or revoked publications answer 404.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{32}$" } } ], "responses": { "200": { "description": "The file (PDF or Word .docx)", "headers": { "X-File-SHA256": { "schema": { "type": "string" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/vnd.openxmlformats-officedocument.wordprocessingml.document": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "This key cannot do that.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/authority-records/{id}": { "get": { "tags": [ "Platforms" ], "summary": "Look up one authority record", "security": [ { "ApiKey": [] } ], "description": "The authority record, the provider and the government it covers, its effective standing (the stricter of the provider's and the record's own) and the three layers of verification (identity, attestation, sampling). Convenience view: the signed status entries in the feed are the authoritative history.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Authority record id." } ], "responses": { "200": { "description": "The record", "content": { "application/json": { "schema": { "type": "object", "properties": { "authority_record": { "$ref": "#/components/schemas/AuthorityRecordView" } } } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "This key cannot do that.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/authority-records/{id}/publications/{external_id}": { "get": { "tags": [ "Platforms", "Providers" ], "summary": "State and history of one publication", "description": "With a platform key: any authority record. With a provider key: only its own records. state is current, withdrawn or revoked. A revoked publication stays revoked until a signed lift entry; the same answer can be derived from the feed.", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Authority record id." }, { "name": "external_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7E]{1,128}$" }, "description": "The provider-chosen publication id (1 to 128 printable characters, no spaces). URL-encode it." } ], "responses": { "200": { "description": "The publication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationState" } } } }, "400": { "description": "The request was not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "This key cannot do that.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Providers" ], "summary": "Withdraw a publication", "security": [ { "ApiKey": [] } ], "description": "Appends a signed removal entry. Repeating returns the existing withdrawal. Refused with 409 while the publication is revoked.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Authority record id." }, { "name": "external_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7E]{1,128}$" }, "description": "The provider-chosen publication id (1 to 128 printable characters, no spaces). URL-encode it." } ], "responses": { "200": { "description": "The withdrawal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishReceipt" } } } }, "400": { "description": "The request was not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "This key cannot do that.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not allowed in the current state (for example the publication is revoked).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/authority-records/{id}/publications": { "post": { "tags": [ "Providers" ], "summary": "Publish, or revise an earlier publication", "security": [ { "ApiKey": [] } ], "description": "A new external_id creates the publication (revision 1). An existing external_id appends a revision that supersedes the previous one. The authority record must be active and belong to the provider. The entry is chained and signed under a write lock.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Authority record id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationInput" } } } }, "responses": { "200": { "description": "The signed entry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishReceipt" } } } }, "400": { "description": "The request was not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "This key cannot do that.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not allowed in the current state (for example the publication is revoked).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/authority-records/{id}/files": { "post": { "tags": [ "Providers" ], "summary": "Upload a file to attach", "security": [ { "ApiKey": [] } ], "description": "Multipart form field \"file\": a PDF or a Word .docx, up to 20 MB. Returns an id to list in the attachments of a publication. The file is bound to this authority record and can be attached once.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "Authority record id." } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "responses": { "200": { "description": "The stored file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FileReceipt" } } } }, "400": { "description": "The request was not valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "This key cannot do that.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "File too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/public-key.json": { "get": { "tags": [ "Public" ], "summary": "Public signing keys", "description": "All keys ever used: active, retired and revoked. Retired keys stay listed so old entries keep verifying. A revoked key carries a signed notice (revoked_at, compromised_since, last_trusted_seq, last_trusted_hash, reason, notice_signed_by, notice_signature): entries it signed are trusted only up to last_trusted_seq. See VERIFICATION.md section 1.3.", "responses": { "200": { "description": "Keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicKeys" } } } } } } }, "/v1/health": { "get": { "tags": [ "Public" ], "summary": "Service health", "description": "Returns {\"status\":\"ok\"} when the database and signing key work, otherwise 503 with the list of problems.", "responses": { "200": { "description": "Healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok" ] } } } } } }, "503": { "description": "Not healthy" } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Also accepted as Authorization: Bearer . Provider and platform keys are created in the account dashboard after approval. A key used on the wrong kind of route answers 403." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "PublicationInput": { "type": "object", "required": [ "external_id", "title", "body" ], "properties": { "external_id": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7E]{1,128}$" }, "title": { "type": "string", "minLength": 1, "maxLength": 300 }, "body": { "type": "string", "minLength": 1, "maxLength": 100000 }, "agency": { "type": "string", "maxLength": 200 }, "source_url": { "type": "string", "format": "uri", "maxLength": 2000, "description": "http or https only." }, "published_at": { "type": "string", "format": "date-time" }, "attachments": { "type": "array", "maxItems": 5, "items": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "description": "File ids from the upload route, for this authority record." } } }, "PublishReceipt": { "type": "object", "properties": { "seq": { "type": "integer" }, "external_id": { "type": "string" }, "authority_record_id": { "type": "integer" }, "state": { "type": "string", "enum": [ "current", "withdrawn" ] }, "revision": { "type": [ "integer", "null" ] }, "supersedes_seq": { "type": [ "integer", "null" ] }, "prev_seq": { "type": [ "integer", "null" ] }, "received_at": { "type": "string", "format": "date-time" }, "removed_at": { "type": "string", "format": "date-time", "description": "Withdrawals only." }, "record_hash": { "type": "string" }, "signature": { "type": "string" } } }, "FileReceipt": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "size": { "type": "integer" }, "sha256": { "type": "string" } } }, "Attachment": { "type": "object", "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "size": { "type": "integer" }, "sha256": { "type": "string" }, "download_url": { "type": "string", "description": "Not signed." } } }, "HistoryItem": { "type": "object", "properties": { "seq": { "type": "integer" }, "type": { "type": "string", "enum": [ "record", "removal" ] }, "revision": { "type": "integer" }, "supersedes_seq": { "type": [ "integer", "null" ] }, "received_at": { "type": "string" }, "record_hash": { "type": "string" } } }, "PublicationState": { "type": "object", "properties": { "authority_record_id": { "type": "integer" }, "external_id": { "type": "string" }, "state": { "type": "string", "enum": [ "current", "withdrawn", "revoked" ] }, "revoked_by_seq": { "type": [ "integer", "null" ], "description": "seq of the status entry that revokes it, if revoked." }, "revision": { "type": "integer" }, "current_seq": { "type": "integer", "description": "Platform keys only." }, "current_revision": { "type": "integer", "description": "Platform keys only." }, "current_record_hash": { "type": "string", "description": "Platform keys only." }, "authority_record_effective_status": { "type": "string", "description": "Platform keys only." }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/HistoryItem" } } } }, "AuthorityRecordView": { "type": "object", "description": "Convenience view of one authority record. Fields: id, effective_status (active, suspended, ended, revoked), effective_status_source (provider, authority_record, both, none), own_status, provider_status, enrolled_at, ended_at, provider {id,name}, government {official_id_type, official_id, name, level, state, county, city, unit_type_text}, verification {identity, attestation, sampling}.", "additionalProperties": true, "properties": { "id": { "type": "integer" }, "effective_status": { "type": "string", "enum": [ "active", "suspended", "ended", "revoked" ] }, "effective_status_source": { "type": "string", "enum": [ "provider", "authority_record", "both", "none" ] }, "own_status": { "type": "string" }, "provider_status": { "type": "string" } } }, "Authority": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "county": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] } } }, "Entry": { "type": "object", "description": "One signed entry. The signed text is built from the fields listed in VERIFICATION.md (the 14 base fields, attachments, then the chain and status fields that are present). The authority object is the feed's grouping of authority_name, authority_type, state, county and city. Fields download_url, removed_at and the signature fields are not part of the signed text.", "required": [ "seq", "type", "record_hash", "signature", "signature_algorithm", "public_key_id" ], "properties": { "seq": { "type": "integer" }, "type": { "type": "string", "enum": [ "record", "removal", "status" ] }, "external_id": { "type": [ "string", "null" ] }, "authority": { "$ref": "#/components/schemas/Authority" }, "agency": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "source_url": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "received_at": { "type": "string" }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } }, "authority_record_id": { "type": [ "integer", "null" ] }, "provider_id": { "type": [ "integer", "null" ] }, "provider_name": { "type": [ "string", "null" ] }, "government_official_id_type": { "type": [ "string", "null" ] }, "government_official_id": { "type": [ "string", "null" ] }, "revision": { "type": [ "integer", "null" ] }, "supersedes_seq": { "type": [ "integer", "null" ] }, "prev_seq": { "type": [ "integer", "null" ] }, "prev_hash": { "type": [ "string", "null" ] }, "status_scope": { "type": [ "string", "null" ], "enum": [ "provider", "authority_record", "publication", null ] }, "status_event": { "type": [ "string", "null" ], "enum": [ "suspended", "reinstated", "ended", "revoked", "revocation_lifted", null ] }, "reason_class": { "type": [ "string", "null" ] }, "reason_code": { "type": [ "string", "null" ] }, "revoked_from_seq": { "type": [ "integer", "null" ] }, "revoked_through_seq": { "type": [ "integer", "null" ] }, "references_seq": { "type": [ "integer", "null" ] }, "removed_at": { "type": [ "string", "null" ] }, "record_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "signature": { "type": "string" }, "signature_algorithm": { "type": "string", "enum": [ "Ed25519" ] }, "public_key_id": { "type": "string" } } }, "FeedHead": { "type": [ "object", "null" ], "description": "Signed statement of the newest entry. Signed text: {\"type\":\"feed_head\",\"seq\":N,\"record_hash\":\"...\",\"signed_at\":\"...\"}; head_hash is its SHA-256; signature is Ed25519 over the head_hash string. Null only on an empty feed.", "properties": { "seq": { "type": "integer" }, "record_hash": { "type": "string" }, "signed_at": { "type": "string" }, "head_hash": { "type": "string" }, "signature": { "type": "string" }, "signature_algorithm": { "type": "string" }, "public_key_id": { "type": "string" } } }, "FeedPage": { "type": "object", "required": [ "entries", "next_after", "has_more", "filter", "feed_head" ], "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/Entry" } }, "next_after": { "type": "integer", "description": "The seq of the last entry returned, or the request cursor if none was returned." }, "has_more": { "type": "boolean" }, "filter": { "type": [ "object", "null" ], "description": "The filter that was applied: {authority_record_id}, {provider_id} or {official_id_type, official_id}; null when the read was not filtered. Not signed: a verifier must be told by its caller that a read was filtered." }, "feed_head": { "$ref": "#/components/schemas/FeedHead" } } }, "PublicKeys": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "properties": { "key_id": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "retired", "revoked" ] }, "algorithm": { "type": "string", "enum": [ "Ed25519" ] }, "encoding": { "type": "string", "enum": [ "hex" ] }, "public_key": { "type": "string" }, "revoked_at": { "type": "string", "description": "Revoked keys only. UTC time the notice was made." }, "compromised_since": { "type": "string", "description": "Revoked keys only. Earliest moment the key may have been in other hands." }, "last_trusted_seq": { "type": "integer", "description": "Revoked keys only. Entries signed by this key are trusted only up to this seq (0 = none)." }, "last_trusted_hash": { "type": "string", "nullable": true, "description": "Revoked keys only. record_hash of that entry (null when last_trusted_seq is 0)." }, "reason": { "type": "string", "enum": [ "key_compromise", "suspected_compromise" ] }, "notice_signed_by": { "type": "string", "description": "Revoked keys only. key_id of the key that signed the notice." }, "notice_signature": { "type": "string", "description": "Revoked keys only. Ed25519 signature (hex) over the SHA-256 of the notice text; see VERIFICATION.md." } } } } } } } } }