# Verify the citations in any document over HTTP

The citation verification API takes a document and the sources it cites and returns a verdict for every citation, a quote-integrity result for every quoted span, a retraction status for every DOI, and an independence audit over the source list. It is built for developers and publishers who need a machine check before something goes out, and it works on documents Hyperresearch did not write: your own draft, your customer's draft, or the raw output of another model's deep research mode.

It is the same code that gates Hyperresearch's own reports. Nothing softer is offered to outside documents.

## Four checks over one request

| Check | What it answers | Result vocabulary |
|---|---|---|
| Cite-check | Does the cited source actually support the sentence that cites it | `supported`, `partially-supported`, `unsupported`, `wrong-source` |
| Quote integrity | Does every quoted span appear verbatim in the source it is attributed to | `verified`, `altered`, `not-found` |
| Retraction sweep | Has any cited paper been retracted, or could its status not be resolved | `ok`, `retracted`, `unavailable`. `expression-of-concern` and `corrected` are in the schema but are never produced today |
| Independence audit | How many of these sources are really one voice | Clusters of kind `url`, `body` or `wire`, plus an effective source count |

`POST /v1/verify/report` runs all four and applies the ship-gate rules. Four narrower endpoints run one check each: `POST /v1/verify/citations`, `POST /v1/verify/quotes`, `POST /v1/verify/retractions` and `POST /v1/verify/independence`. The retraction endpoint takes a bare `dois` array and needs no document at all, which is the cheapest way to sweep a bibliography.

[What a receipt contains](/verification-receipt) documents every field the checks return.

## Request shape

All five creation endpoints take the same JSON body. Every field is optional at the schema level; which ones you need depends on the check.

| Field | Type | What it is |
|---|---|---|
| `document_md` | string | The document, in Markdown. Numbered `[N]` citations with a sources list, inline links, footnotes and wikilinks `[[note-id]]` are all read |
| `sources` | array | The source list. Each entry may carry `n`, `note_id`, `text`, `url`, `title`, `author`, `year` and `doi` |
| `dois` | array of strings | DOIs to sweep, for the retraction check without a document |
| `sample` | `"all"`, `"strong-markers"`, or a number from 0 to 1 | How much of the document reaches the model tier |
| `policy.allow_unsupported` | boolean | Report unsupported and wrong-source pairs without failing the gate |
| `policy.allow_retracted_if_noted` | boolean | Pass a retracted citation the document itself describes as retracted |
| `persist` | boolean | Keep the submitted sources in your workspace vault instead of the 7-day ephemeral one |
| `normalise` | `"auto"` or `"off"` | `auto` (the default) rewrites inline links and footnotes to numbered citations before checking |
| `max_llm_pairs` | integer | The most pairs to read in this document, or claims on a pasted answer; those past it are reported as not checked and not billed |

Sources get in three ways. Send `text` and nothing is fetched, which is the cheapest path and the way to verify against a private document. Send `url` and the page is fetched through the same fetch ladder a research run uses. Send `note_id` and the source is read from your workspace vault.

An optional `Idempotency-Key` request header is accepted, so a retried submission does not create a second billable job.

## Response shape

Creation returns `202` with the job, not the result:

| Field | Notes |
|---|---|
| `id` | The verification id, used in both read paths |
| `status` | `queued` |
| `checks` | Which checks this job will run |
| `usage_event_id` | A stable reference for this job |
| `receipt_url` | `null` at creation |
| `created_at` | ISO timestamp |

`GET /v1/verify/{id}` returns `id`, `status`, `pairs_total`, `pairs_llm`, `price_cents`, `usage_event_id`, `created_at`, `finished_at` and `error`. `pairs_total` and `pairs_llm` are the two numbers that matter operationally: how many citation-sentence pairs the document contained, and how many of them reached the model tier and are therefore billable.

`GET /v1/verify/{id}/result` returns `id`, `status`, `receipt_url` and `receipt`. The receipt is inline; `receipt_url` is an HMAC-signed reference to the durable copy in storage and expires after about an hour.

## A verification in three calls

```bash
curl -sS https://api.hyperresearch.ai/v1/verify/report \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: draft-4821-pass-1" \
  -d '{
    "document_md": "Installed battery storage reached 42 GW in 2024 [1], and capacity grew 60% year over year [2].\n\n## Sources\n1. Market report\n2. Trade press summary",
    "sources": [
      { "n": 1, "title": "Market report", "text": "Installed capacity stood at 42 GW at the end of 2024." },
      { "n": 2, "url": "https://example.org/storage-2024", "doi": "10.1000/example.2024.001" }
    ],
    "sample": "all"
  }'
```

```bash
curl -sS https://api.hyperresearch.ai/v1/verify/abc123 \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```

```bash
curl -sS https://api.hyperresearch.ai/v1/verify/abc123/result \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```

Poll the status endpoint until `status` is terminal, then read the result. A 200-citation report with around 60 pairs reaching the model tier typically returns in under a minute; a 40,000-word document with hundreds of citations runs as a background workflow and delivers a `verify.done` webhook.

## What it costs

Verification is paid from your Hyperresearch balance, by the pair that has to be read: 5¢ each, at least 5¢ a check. Pairs that clear the mechanical triage are free, and quote integrity, the retraction sweep and the independence audit are included in that minimum. New accounts usually start with $5 of credit and no card on file, which covers 100 read pairs. The status response reports `pairs_total` and `pairs_llm`, so the bill is reconcilable against what was actually read, and `price_cents` on the same response is the exact amount charged.

A check sets aside what it may cost and gives back the rest. Pairs your balance cannot cover are reported as not checked and not charged, and a balance under 5¢ is refused with `402 insufficient_balance`. See [pricing](/pricing) for plans.

## Limits

- The request schema caps `document_md` at 8 MB.
- Up to 500 sources per request, each source `text` up to 2 MB.
- Up to 100 DOIs in a `dois` sweep.
- Citation extraction covers numbered `[N]` citations with a sources list, inline Markdown links, footnotes `[^N]` and wikilinks `[[note-id]]`. Author-year citations are not read.
- Text only. Figures, tables published as images, and audio are out of scope.
- Submitted documents and sources are deleted 7 days after the job finishes unless you sent `persist: true`. The receipt is kept.

## The scope you need is `verify`

Every endpoint on this page requires an API key or agent connection carrying the `verify` scope. Scopes are per key, set when the key is created, and visible in the console. An agent connected over MCP gets read-only scopes by default; `verify` is a metered action and has to be granted separately, because it spends money.

## How this differs from reference checkers

Most citation-checking tools answer one question: does this reference exist. They take a reference list, resolve the DOI, compare the metadata against Crossref, PubMed, arXiv or OpenAlex, and tell you whether the paper is real and whether the author, year and title match. SourceVerify does this through an API with per-field labels. GPTZero's hallucination detector does it for students and educators across a large scholarly index. A dozen free web tools do the same thing with a paste box. That check is genuinely useful, and a fabricated reference is a real failure mode worth catching; [the five ways an AI citation fails](/ai-citation-checker) shows which kind of checker catches which.

This API answers four different questions, and existence is not one of them:

- Does the cited source's text support the sentence that cites it. This requires reading the source body, not its metadata record.
- Is every quoted span intact. A real paper, correctly cited, can still be quoted with words changed or dropped.
- Has the paper been retracted. A retracted paper resolves perfectly and matches its metadata exactly, so a metadata check cannot see it. The `retracted` status comes from OpenAlex's `is_retracted` flag. The Crossref fallback, used when OpenAlex has no record, does not currently detect retractions. Expressions of concern are in the schema but are never produced today. [Retraction-aware research](/guides/retraction-aware-research) has the detail.
- Are these citations independent. Five citations to five URLs carrying the same wire story are one voice, and a metadata check has no reason to notice.

Scite's Smart Citations is a third thing again, and worth knowing about for a different job: it classifies how the published literature cites a paper, supporting or contrasting or mentioning, across millions of citation statements. That tells you how a paper has been received. It does not tell you whether your sentence is supported by the source you attached to it. The two are complements, not substitutes.

If your failure mode is a fabricated reference, a metadata checker is the cheaper tool and you should use one. If your failure mode is a real reference attached to a sentence it does not support, that is what this API is for.

## Try it without an account

The public demo at [/verify](/verify) is not taking submissions at the moment. The same four checks run on a pasted document from the console once you have an account.

The demo is deliberately small: up to 20,000 words of document, up to 8 sources, up to 10 DOIs, and up to four pairs read per submission, with the receipt kept for 24 hours and three submissions per network per day. Vault note ids are refused outright, because an anonymous caller must not be able to read a workspace. Everything above those limits is the API on this page.
