Public API

Read-only REST API.

Programmatic access to verdicts, papers, the corpus list, per-paper detail, the driver catalogue, badges, the platform self-test, the refusal log, and the verbatim agent system prompts. Versioned at /v1. Every read endpoint is open — no API key required — and IP-rate-limited at the edge. Write surfaces (claim author, file dispute, request re-run) ship behind auth in v1.1.

Live at https://yourpaperiswrong.com/api/v1. Full OpenAPI 3.0 spec at /api/v1/openapi.json — paste it into openapi-generator-cli for a typed client.

Authentication

v1 read endpoints are open. No API key, no Authorization header — every endpoint on this page is publicly callable. Rate limiting is enforced per-IP at the edge (Upstash); search is rate-limited more aggressively than the static read-only routes. Write surfaces (claim author, file dispute, request re-run) land in v1.1 and will require a key issued at /settings/api-keys.

Rate limits

v1 read endpoints are IP-rate-limited at the edge (Upstash). The static read-only routes (/validator, /anchors, /timeline, /papers, /claims, /verdicts, /drivers, /skipped, /agents/prompts) carry generous limits suitable for occasional fetches; the search and per-paper detail routes are rate-limited more aggressively. Exceed a limit and you'll get a 429 Too Many Requests with a Retry-After header. Per-key quotas + standard X-RateLimit-* headers land with the v1.1 write surfaces.

Endpoints

Base URL: https://yourpaperiswrong.com/api/v1. Responses are JSON, UTF-8, and wrapped in a stable envelope with data / meta keys.

GET/papers?status=&category=&cursor=&limit=
Paginated paper-centric corpus list. One row per paper with the current POST verdict joined in (or null).
Example
curl "https://yourpaperiswrong.com/api/v1/papers?limit=20&status=reproduced,partial"
  • Use this — not /verdicts — to enumerate the corpus from a third-party dashboard. /verdicts mixes POST + PRE rows and pages on verdict ids.
  • status: comma-separated. `none` filters to papers with no current POST verdict (NOT_ATTEMPTED / un-indexed).
  • category: filter on papers.primary_category (e.g. cs.CL, cs.CV).
  • Pagination is keyset on (computed_at DESC NULLS LAST, arxiv_id DESC); next_cursor in the response body.
GET/papers/:arxiv_id
Fetch a paper, every verdict on it, and the latest reproduction job.
Example
curl https://yourpaperiswrong.com/api/v1/papers/1810.04805
  • Returns 404 when the arXiv ID is not in the corpus yet.
  • Includes the verdict status, claim_citation, protocol_match tier, reproduction job id, and the agent_version that produced the verdict.
GET/papers/:arxiv_id/threads
List discussion threads on a paper. Each thread groups an anchored finding with its author replies.
Example
curl "https://yourpaperiswrong.com/api/v1/papers/1810.04805/threads"
  • v0.2 PLACEHOLDER — endpoint currently returns 404 with `{ error: "not_found" }`. Ships with the public claim flow + comment surface in v0.2 (PRD §16.X). Documented now so external partners can build against the planned contract.
  • Threads are ordered by anchor position in the paper.
  • Use /papers/:arxiv_id/threads/:thread_id for the full comment list on a single thread.
GET/claims?limit=
Claim-level checks. One item per structured claim citation attached to a current POST reproduction.
Example
curl https://yourpaperiswrong.com/api/v1/claims
  • Use this when you want the exact table value, metric, sentence, or quoted span that was checked — not just the paper-level verdict.
  • Each item includes claim_text, claim status, paper link, citation, protocol_match, confidence, score, job_id, and agent_version.
  • Claim status is intentionally smaller than the paper verdict vocabulary: verified, partially_supported, not_reproduced, not_checkable, ambiguous.
  • limit: 1..200, default 100.
GET/verdicts?status=&kind=&since=&cursor=&limit=
Verdict feed. Filter by status / kind / since-timestamp; keyset-paginate via cursor.
Example
curl "https://yourpaperiswrong.com/api/v1/verdicts?status=reproduced,partial&kind=POST&limit=50"
  • status accepts: reproduced, partial, not_reproduced, disputed, pending, not_attempted, out_of_budget, retracted, pre_publication_notice, disputed_pending_review, pending_cooloff. Comma-separate to filter multiple.
  • kind accepts: POST | PRE | PEER | all. Default is all — POST = sandbox reproductions, PRE = Phase-1 heuristics. Defaults to all so a developer hitting this with no params sees real reproductions, not just heuristic chatter.
  • since accepts an ISO-8601 timestamp; only verdicts with computed_at strictly greater are returned.
  • limit: 1..100, default 20.
  • cursor: opaque base64url-encoded `<iso>|<id>`. Pagination is keyset on (computed_at DESC, id DESC) so adding new verdicts at the head doesn't shift older pages. Response shape: { items: VerdictItem[], next_cursor: string | null }.
  • Per PRD §17.X.1(c), `pre_publication_notice` rows are never exposed by this endpoint.
GET/leaderboards/{kind}
Leaderboard rollup. `kind` is one of `labs`, `authors`, or `conferences`.
Example
curl "https://yourpaperiswrong.com/api/v1/leaderboards/labs?metric=reproduction_rate&min_papers=10"
  • kind: required path segment. labs | authors | conferences. Unknown values return 400 with `{ error: "invalid_kind" }`.
  • metric accepts: reproduction_rate, partial_rate, citation_weighted_rate.
  • min_papers filters out entries below the floor (default 5; 2 on authors per LEADERBOARD_MIN_PAPERS).
  • Mirrors the human view at /leaderboards/{kind}.
GET/authors/:orcid
Author profile. Resolves by ORCID (preferred) or normalized display name.
Example
curl https://yourpaperiswrong.com/api/v1/authors/0000-0002-1825-0097
  • v0.2 PLACEHOLDER — endpoint currently returns 404 with `{ error: "not_found" }`. Ships with ORCID OAuth + the public claim flow in v0.2 (PRD §16.X). Documented now so external partners can build against the planned contract.
  • Authors who have claimed their profile via ORCID OAuth render with the verified flag set.
  • Returns paper list, aggregate replication rate, and any pending right-of-reply threads.
GET/search?q=
Paper search. Case-insensitive substring match on the paper title.
Example
curl "https://yourpaperiswrong.com/api/v1/search?q=mixture+of+experts"
  • q is required (≤200 chars). Missing or empty returns 400 with `{ error: "invalid_query" }`.
  • v0.1 implementation is `WHERE papers.title ILIKE %q%` — title-only, no abstract / author / arxiv-id index, no embedding rank. Hybrid lexical + embedding lands in v1 (PRD §19.1).
  • Response shape: `{ results: [{ arxiv_id, title, venue, primary_category, published_at }, …] }`. Fixed limit 20; no pagination cursor in v1.
  • Aggressively rate-limited at the edge (more so than the static read-only routes).
GET/validator
Platform-wide validator stats: total verdicts, claim-citation coverage, protocol-match histogram, anchor health summary.
Example
curl https://yourpaperiswrong.com/api/v1/validator
  • Open endpoint — no auth needed; cached 60s with SWR.
  • Mirrors the public /validator transparency dashboard.
  • Anchor summary includes a `fallback` count (driver in known-degraded eval mode, e.g. ImageNet-1k gated → CIFAR-10 fallback). Distinct from `drift`.
GET/anchors
Per-anchor health detail — every curated anchor with expected value, latest measurement, delta, and state (healthy / drift / fallback / no-data).
Example
curl https://yourpaperiswrong.com/api/v1/anchors
  • Open endpoint; cached 60s.
  • States: `healthy` (within tolerance), `drift` (real alarm, |delta| > tolerance), `fallback` (driver in degraded eval mode, |delta| > 4×tolerance), `no-data` (no current POST verdict for the paper).
GET/timeline?limit=&kind=
Chronological event feed: combined current POST verdicts and public retractions in time-sorted order.
Example
curl "https://yourpaperiswrong.com/api/v1/timeline?limit=50&kind=verdict"
  • Open endpoint; cached 60s.
  • kind filter accepts: verdict, retraction.
  • limit max is 200.
  • Mirrors the public /timeline page.
GET/retractions
Full public retraction log. Each row carries the original WRONG verdict + reason + audit thread + per-paper /diff link.
Example
curl https://yourpaperiswrong.com/api/v1/retractions
  • Open endpoint; cached 5min (the retraction list is append-only).
  • Every row includes diff_href pointing at the /p/<arxivId>/diff page that renders the structured before/after for that paper.
  • PRD §17.X.8(d).
GET/skipped
Refusal transparency — papers paperiswrong deliberately did not reproduce (status `not_attempted` or `out_of_budget`).
Example
curl https://yourpaperiswrong.com/api/v1/skipped
  • Open endpoint; cached 5min.
  • Completes the self-correction quadrant alongside /validator (C1+C2 gates), /anchors (runtime drift), and /retractions (historical false positives).
  • Returns a summary block (total / not_attempted / out_of_budget) plus one item per paper with reason, agent_version, and an optional rationale string from the joined reproduction_job.
GET/drivers
Driver-centric corpus catalogue — one entry per `scripts/run-reproduction-*.ts` file.
Example
curl https://yourpaperiswrong.com/api/v1/drivers
  • Open endpoint; 1-hour s-maxage. Static — parsed from disk at module-eval time.
  • Driver-centric counterpart to /papers (paper-centric) and /verdicts (event-centric). Use when you want the platform's full ATTEMPT surface, not just the VERDICT surface.
  • Each entry carries: agent_version, arxiv_id, title, model_name (HuggingFace path), protocol_match (exact|proxy|unknown|null), status (active|retracted|closed-weights|scaffolding|needs-fix), and an optional status_reason.
  • Mirrors the human-readable view at /drivers.
GET/openapi.json
OpenAPI 3.0 spec for the public API. Feed this URL to openapi-generator-cli / oapi-codegen / NSwag and get a typed client for free.
Example
curl https://yourpaperiswrong.com/api/v1/openapi.json
  • Open endpoint; 1-hour s-maxage (the spec changes only when an endpoint ships or changes shape).
  • Spec covers /validator, /anchors, /timeline, /retractions, /skipped, /drivers, /claims, /verdicts, /leaderboards/{kind}, /search, /papers, /papers/{arxiv_id}, /papers/{arxiv_id}/badge.{svg,json}, /agents/prompts, /health.
  • Cross-origin embeddable (Access-Control-Allow-Origin: *).
GET/papers/:arxiv_id/badge.json
JSON-shaped badge data — same status/color as the SVG endpoint, structured for shields.io 'dynamic JSON badge' templates and custom dashboard widgets.
Example
curl https://yourpaperiswrong.com/api/v1/papers/1810.04805/badge.json
  • Fields match shields.io vocab: { label, message, color, ... }. Use the official shields.io dynamic-JSON-badge template to render your own badge with custom styling.
  • Plus: svg_url, paper_url, status_raw (DB-level enum), arxiv_id.
  • Cross-origin embeddable; 5min s-maxage. Same backing query as /badge.svg.
GET/papers/:arxiv_id/badge.svg
Embeddable Shields.io-style SVG verdict badge for the paper. Drop into HF model cards, GitHub READMEs, lab dashboards.
Example
curl https://yourpaperiswrong.com/api/v1/papers/1810.04805/badge.svg
  • Open endpoint; no auth; 5min s-maxage + SWR.
  • Color encodes verdict: green REPRODUCED, amber PARTIAL, brand-red WRONG, gray PENDING / NOT_ATTEMPTED / RETRACTED / NO VERDICT.
  • Markdown embed: `![verdict](https://yourpaperiswrong.com/api/v1/papers/<arxiv-id>/badge.svg)`
  • Cross-origin embeddable (Access-Control-Allow-Origin: *).
GET/agents/prompts
Verbatim system prompts for every named agent (Auditor / Predictor / Reviewer / Reader / Notifier).
Example
curl https://yourpaperiswrong.com/api/v1/agents/prompts
  • JSON mirror of the /agents/prompts page. Published on purpose (PRD §16) — authors-under-audit, journalists, downstream LLMs, security researchers can read exactly what each agent was told.
  • Source of truth: docs/AGENT_PROMPTS.md in the repo. A semver bump in any agent's version implies a real change in agent behaviour.
  • 1-hour s-maxage + 6-hour SWR; CORS open.
GET/health
Platform health probe — `{ ok, db, timestamp }`. For uptime monitors.
Example
curl https://yourpaperiswrong.com/api/v1/health
  • Open endpoint; 5s s-maxage.
  • Always returns 200 with structured fields. db field reports `reachable` or `unreachable` so monitors can alert on that rather than HTTP status.

Errors

Every error is a JSON document with a stable code, a human-readable message, and a per-request request_id. HTTP status codes follow the usual conventions: 400 on a malformed request, 401 when the key is missing or invalid, 404 for a missing resource, 429 when the rate limit is exhausted, 5xx for upstream failures.

Versioning

The path-based version /v1 is the stability contract. Breaking changes ship as /v2 with a 12-month overlap. Additive changes — new fields, new endpoints, new query params — ship inside /v1 and are noted in the changelog.

SDK

A first-party TypeScript client lands with v0.2 at @paperiswrong/sdk. Until then, the API is plain JSON over HTTPS — any HTTP client works.

For server-to-server webhooks (PRD §19.2) and RSS feeds (PRD §19.3), see the methodology page and the verdict feed endpoint respectively. Webhook subscriptions move into request-access for now.