Poliety is a news feed for AI agents. Humans can read it too. The site at poliety.com, its feeds and /api/latest.json are free and always will be. This keyed API adds what a static site cannot: memory. History, change cursors and filtered queries.
Every /v1 endpoint requires a key in the Authorization header, except the free event feed: /v1/events and /v1/events/<id> take no key at all. Checkout is hosted by Stripe and keys start at $19 a month; your key is shown immediately after checkout, exactly once.
curl -H "Authorization: Bearer YOUR_KEY" https://api.poliety.com/v1/changes
Keys ride in the header only. Requests with keys in the URL are rejected: URLs leak into logs.
Agents: the offer itself is machine-readable at /offer.json, every keyed 401 embeds the price and checkout, and the post-checkout claim page at /claim answers JSON when the request carries Accept: application/json, so a key your operator paid for is collectable without scraping HTML.
| Endpoint | What it returns |
|---|---|
GET /v1/latest | The current edition (schema poliety.edition.v1) with per-item contentHash and firstSeenAt. Sends ETag; answer If-None-Match and unchanged editions cost you nothing (an unmetered 304). |
GET /v1/changes | Everything new since your last call. Pass the cursor from the previous response. Filters: section, minScore, change (added, updated, score_changed, aged_out), kind (wire, brief), limit. First call without a cursor returns a starting cursor. since (ISO 8601 time) is accepted as a coarser alternative. |
GET /v1/wire | Query the wire history. Filters: section, minScore, since, until (publication time), source, active=1 (currently live items only), limit. |
GET /v1/editions | The edition hash chain: every archived day with contentHash and prevHash. Record a hash and you can detect any silent rewrite of history. |
GET /v1/editions/<date> | One archived edition, byte-faithful as ingested. |
GET /v1/items/<id> | One wire item with its full event history and firstSeenAt: when Poliety first observed it. |
GET /v1/usage | Your own meter for the last 7 days. What we count is what you can see. |
GET /v1/events | Unauthenticated and unmetered. Canonical events: material changes in the AI and software ecosystem (status transitions, SDK releases, pricing and spec changes), each Bench-governed, provenance-backed and hash-chained. Pass the next_cursor from the previous response as since to receive only newer events. Filters: type, entity, min_materiality, limit. |
GET /v1/events/<id> | Unauthenticated. One canonical event by its evt_ id, byte-faithful as published, plus its current derived status (a superseding correction flips it without touching the original). |
GET /v1/events/<id>/evidence | The assembled evidence package for one event: epistemic detail (recorded and current status, confidence, rationale, sources by authority), the full Bench tribunal receipt (verdict, constitution hash, challenger findings, defender rebuttals, oracle reasoning), integrity hashes with links to the free published files so every hash is independently checkable, and full provenance. Requires a key. |
GET /v1/events/<id>/history | The event's supersession lineage, oldest first: what was believed at each point, at what confidence, and what corrected it. Later entries supersede, never overwrite. Requires a key. |
POST /v1/concierge | The Agent Concierge. Body {"question": "..."} (1 to 2000 chars). Grounded Q&A about this service: coverage, capabilities, tiers. No key required; a key raises the rate limit. Answers carry canonical: false and are never citable as Poliety claims; the canonical_urls field lists the published surfaces that are. |
GET /health | Unauthenticated liveness check. |
GET /offer.json | Unauthenticated. The machine-readable commercial offer: price, limits, checkout URLs, key lifecycle and terms, for agents deciding whether to buy. Every keyed 401 embeds a compact version. Sends ETag. |
GET /integrity.json | Unauthenticated. The chain head, root and length, plus a one-line witness recipe. No key needed: an integrity claim you cannot check without paying is not an integrity claim. Sends ETag keyed to the chain state, so polling on If-None-Match is a 304 until the chain moves. |
Builder keys: 60 requests a minute, 5,000 metered requests a day. Conditional 304s are not metered. Rate-limited responses carry Retry-After. Need more? Email dburks@poliety.com.
The concierge answers questions about this service, grounded strictly in the published docs and terms; it never invents features or prices and has no authority to set prices, grant discounts, or transact. Its answers are conversational, non-canonical and non-contractual: only the published surfaces (editions, API responses, integrity.json, these docs) are citable Poliety claims. Anonymous callers get 3 questions a minute and 20 a day; keyed callers get their key's normal limits. A global daily budget cap shuts the endpoint with a 503 rather than degrading it.
Item and brief contentHash values are sha256 over canonical JSON of the content fields (score excluded), identical to the hashes in the free latest.json. All text is sanitized plain text: no HTML, no control characters, safe to place in a context window.
Editions form a hash chain, each linked to the nearest earlier date by prevHash. Editions for dates before the head never change once a later edition exists. The head is the current date's row and is replaced whenever the site rebuilds, so its hash can move until the date closes: witness it after the day rolls over, or verify it through the next day's prevHash.
Verify it yourself against the free site, no key required:
curl -sS https://poliety.com/api/latest.json | shasum -a 256 curl -sS https://api.poliety.com/integrity.json
The digest matches chain.head.contentHash when the site and the chain are in sync. Record chain.head daily and the next day's prevHash has to match what you recorded, which makes a silent rewrite detectable by anyone who bothered to look once. Being straight about the limit: this chain is served by the same operator that writes it, so it proves internal consistency and nothing more. It is not a third-party notary and the editions are not signed. Ed25519 signatures and a published transparency log are on the roadmap.
poliety.edition.v1 and poliety.changes.v1 never break: fields are only ever added, never renamed, retyped or removed. Breaking changes would ship as a v2 alongside a still-working v1.
This service stores: a derived key id, a sha256 hash of your key (never the key itself), your plan, your Stripe subscription id, per-day request counters per endpoint, and concierge transcripts (the question, the answer, a timestamp, and the derived key id when a key was presented; anonymous questions carry no identity at all). Payment details live with Stripe and never touch this service. Logs carry the key id, path and status. We do not store IP addresses; transient platform logs at our host are outside our retention. Cancel any time; keys deactivate automatically within a day of cancellation or refund.
If your assistant supports MCP, you can skip the HTTP calls entirely. The Poliety MCP server is a zero-dependency stdio adapter that wraps this API. Seven tools: poliety_latest (current edition), poliety_changes (cursor-based deltas with all the filters above), poliety_integrity (chain proof, no key required), poliety_events (canonical event feed, no key required), poliety_event_evidence and poliety_event_history (the keyed evidence surface), and poliety_ask (the concierge, no key required).
Add it to your MCP client config:
{
"mcpServers": {
"poliety": {
"command": "npx",
"args": ["-y", "poliety-mcp"],
"env": { "POLIETY_API_KEY": "YOUR_KEY" }
}
}
}
Package: poliety-mcp on npm. Node 22+.
The free tier is the whole site: llms.txt, JSON Feed, RSS and latest.json with full article text. It stays free, with attribution. This API exists so the lights stay on.