Quorum-API

<div align="center">

# Quorum

**Market evidence with receipts.**

Give it a subject, get back what a market actually says. Every claim carries
receipt ids, and every receipt id resolves to a real stored record you can fetch
back. Fabricated citations are structurally impossible, and a test proves it
rather than a README asserting it.

[![CI](https://github.com/Godzilla-lab/Quorum-API/actions/workflows/ci.yml/badge.svg)](https://github.com/Godzilla-lab/Quorum-API/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D22.18-brightgreen.svg)](https://nodejs.org)
[![npm](https://img.shields.io/npm/v/quorum-api.svg)](https://www.npmjs.com/package/quorum-api)
[![Tests](https://img.shields.io/badge/tests-1%2C233-brightgreen.svg)](#development)
[![Runtime dependencies](https://img.shields.io/badge/runtime%20dependencies-1-brightgreen.svg)](#requirements)
[![OpenAPI](https://img.shields.io/badge/OpenAPI-3.1-6ba539.svg)](spec/openapi.yaml)

</div>

> [!TIP]
> The interesting part is not that it finds evidence. It is that you can check
> it. Every id in every answer resolves through `GET /v1/evidence/{id}`, and
> `POST /v1/verify` will re-resolve a set of claims against the corpus, ours or
> anybody else's. An id that does not resolve is a claim that was never real.

```json
{
  "finding": "Sizing runs small, and buyers only discover it after delivery",
  "corroboration": { "records": 31, "channels": 5 },
  "receipts": ["rc_8f2a1", "rc_44b0e", "rc_91c37"],
  "confidence": "finding"
}
```

`GET /v1/evidence/rc_8f2a1` returns the actual comment, its score, where it was
posted, when, and its permalink. A customer of your customer can click a claim
and read the human who said it.

The hosted API lives at **https://quorum-api-j15n.onrender.com**, on a free
tier instance that sleeps when idle, so the first request after a quiet spell
waits a few seconds for it to wake.

**The hosted instance is keyed while the API is early.** The
[API root](https://quorum-api-j15n.onrender.com) says how to request a key,
and always says which mode the instance you are talking to is in. The health
endpoint needs no key, so you can check it is alive right now:

```bash
curl https://quorum-api-j15n.onrender.com/v1/healthz
```

Self hosting supports open mode or per key auth, quotas, tenancy and webhook
secrets, all self served from `GET /v1/usage`.

> [!NOTE]
> On Windows, the curl bundled with Git Bash uses the Schannel TLS stack,
> which refuses any HTTPS connection when it cannot reach the certificate
> revocation servers (`CRYPT_E_REVOCATION_OFFLINE`, common behind corporate
> proxies and VPNs). That is the network, not this API. Add
> `--ssl-revoke-best-effort` to the curl command, or call from WSL or
> PowerShell instead.

## Contents

- [What it does](#what-it-does)
- [Use cases](#use-cases)
- [Status](#status)
- [Requirements](#requirements)
- [Quick start](#quick-start)
- [Usage](#usage)
  - [CLI](#cli)
  - [HTTP API](#http-api)
  - [JavaScript SDK](#javascript-sdk)
  - [Python SDK](#python-sdk)
  - [MCP server](#mcp-server)
  - [Webhooks](#webhooks)
  - [Running the API yourself](#running-the-api-yourself)
  - [Postgres](#postgres)
- [What the API does](#what-the-api-does)
- [Why this is different](#why-this-is-different)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [License](#license)
- [Acknowledgements](#acknowledgements)

## What it does

Voice of customer from public archives, competitor ads ranked by how long they
have actually been running, and a video versus static verdict computed as
arithmetic rather than opinion. It keeps everything it reads, so the second
question about a market is nearly free and the archive can be asked about the
past.

**Key capabilities**

- **Receipts, not links.** A stable id into a retained corpus, which resolves
  identically forever, including after the source deletes the original.
- **Corroboration as arithmetic.** A claim needs at least three independent
  records before it prints as a finding, and the count travels with it.
- **Ten sources behind one interface**, from a volunteer Reddit archive and
  GitHub issue search to four government safety regulators, each degrading
  rather than failing when unconfigured.
- **A corpus that compounds.** Cold retrieval measured 596 seconds and about 500
  throttled requests. The same category answers in half a second once warm.
- **Offline mode** that touches no network and costs nothing.
- **Fifteen HTTP operations, a typed SDK, an MCP server and a CLI**, all the same
  pipeline.

### What it looks like

Real output, excerpted from a cold `npx quorum "espresso machine"` run on
2026-08-24: 401 records in 227 seconds for $0.00.

```
EVIDENCE  a claim needs 3 independent receipts to be stated as a finding
          the percentage is share of all 401 records held for this category

  quality     88 receipts /  64 channels  21.9%  A0 B3 C85 D0   [finding]
      "I often hear the priority list being 1. Quality of beans 2. Quality
       of the grinder 3. Quality of the espresso machine..."
         hackernews Why a spritz of water before grinding coffee yields
         better results   rc_4d6d444821b0044f

ATTESTED  7 records from 6 named parties   [finding]
  A named party stated this to a regulator, on the record, with consequences
  for lying. Two of these are a finding on their own.

      "CPSC And Krups Announce Action On Espresso Makers..."
         cpsc Krups   rc_a4883bfb1b04d1c1

RECEIPTS  195 cited, 195 resolved back to real records

COST      $0.0000 in 227.3s
```

Every id in that output is fetchable from the corpus that run wrote. If an id
does not resolve, the run exits non zero and says which one.

## Use cases

- **Product and brand research.** What buyers actually complain about, with the
  comment behind every claim, rather than a summary you have to trust.
- **Competitive teardown.** One full retrieval per rival, so shares are compared
  instead of counts, and co-occurrence is never mistaken for a signal.
- **Ad creative decisions.** Video versus static judged by how long real
  campaigns ran, from dated observations rather than from a platform's own
  label.
- **Agent tooling that can be audited.** An MCP server whose every claim the
  calling model can independently resolve, which is the one thing a research
  tool cannot fake.
- **Diligence and monitoring.** Attested records a named party filed with a
  regulator, and a diff against the last report for the same subject.

## Status

| | |
|---|---|
| **Engine** | Working. 1,233 tests, offline and keyless |
| **CLI** | Working, every flag |
| **MCP server** | Working, five tools over stdio, four of them also remote at `/mcp` |
| **JavaScript SDK** | Working, 11 methods |
| **Python SDK** | **Published**: `pip install quorum-api`. 14 methods, standard library only |
| **Webhooks** | Working. Signed to Standard Webhooks, durable, retried for about 75 hours |
| **Hosted API** | **Deployed and live** at https://quorum-api-j15n.onrender.com, on PostgreSQL, verified against the running instance |
| **npm** | **Published**: `npx quorum-api "running shoes"`. Five packages, zero external dependencies |
| **Corpus** | Young. 22 consumer and developer categories warmed on the hosted instance as of 2026-08-25; everything else is a cold run away |

> [!NOTE]
> **Do not depend on the API shape yet.** It is stable enough to build against
> and not yet frozen.
>
> Named rather than left as a surprise: **request quotas are held in memory**,
> so the per minute lookup counter resets on restart and none of the counters
> would hold across two instances. The hourly report counter is the exception:
> it is re-seeded from persisted reports at boot, so a restart is not a refill.
> And **`evals/` holds only its first layer**, a labelled relevance set scored
> in CI; the paid, scored report evals described in the project docs do not
> exist yet.

## Requirements

**Node 22.18 or newer**. The engine has **one runtime dependency**, `pg`, and
only in the hosted server: no framework, no ORM, no HTTP client, no test runner,
and nothing at all in the CLI or the corpus. That is a deliberate constraint
rather than a boast, because every dependency in a tool that fetches untrusted
text from the public internet is another thing that can reach the network on
your behalf. `pg` earned its place by being a connection pool that survives a
database restart, which is not a thing worth hand writing.

No key is required for anything. Reddit through a public archive, Hacker News,
the App Store and four government safety archives are all free and keyless. Keys
only ever ADD sources, and a missing one degrades a run rather than failing it.

<details>
<summary><strong>Environment variables</strong>, all optional. Put them in a gitignored <code>.env</code> at the repo root.</summary>

| | |
|---|---|
| `QUORUM_CONTACT_EMAIL` | Not a key. The SEC requires a User-Agent naming who is calling and returns 403 without one, so `sec-edgar` reports itself unconfigured until this is set. A role address outlives whoever set it up. |
| `OPENROUTER_API_KEY` | Subject expansion, `--synthesise` and `--read-images`. All three are off by default, and the counts never come from a model, so the deterministic report is identical without it. |
| `APIFY_TOKEN` | The Meta ad library, and the only metered source in the repo. Every call charges the cost meter and lands on the report's bill. Absent, the ads leg is skipped exactly as `--no-ads` does. |
| `QUORUM_CORPUS` | SQLite corpus path, read by the **server and the MCP server**. Default `./quorum.db`. The CLI does not read it: pass `--corpus` instead. |
| `QUORUM_PG_URL` | Postgres, for the hosted corpus. Paste the provider uri whole: it is parsed rather than split, so `sslmode` is honoured and a password containing `@` survives. |
| `QUORUM_PG_CA` | Path to the provider CA. Worth settin