Check a paper's citations · Life sciences

Use it from your codeThe hosted API with your key, and prompts to paste into a coding agent

Hosted · by Decosa

Get an API key

Call the citation and claim checker for papers API from your own code in minutes.
Every model answer carries a signed receipt.
Nothing to install; we run the models.

Self-host · your GPUs

Run it yourself, on request

The same open models and app, on 1× RTX PRO 6000 (96 GB) or 1× RTX 5090 (32 GB) for the model; parsing and the reference checks run on CPU.
Data never leaves your machines, and there are no Decosa charges.
One prompt for Claude Code or Codex assembles the whole stack.
Early access: the container images are not public yet and the source needs access; the prompt says how to ask.

Get the assembly prompt

Build with it

Paste one of these into Claude Code, Codex or another coding agent. The first wires your project to the hosted API with your DECOSA_API_KEY. The second pulls our containers and runs the same stack on your own GPU, with no Decosa charges.

Base URL: https://api.decosa.ai
Auth: Authorization: Bearer $DECOSA_API_KEY (or a demo session token)
Tool id: paper-claim-check

Use the hosted API

# Decosa citation and claim checker: use the hosted API

You are wiring Decosa's citation and claim checker into this project. It takes a manuscript with its reference list and
returns: every reference checked against Crossref and OpenAlex (retracted, withdrawn, corrected, a DOI that does not
exist or points to another paper, a wrong year or first author), every citing sentence checked against the cited
paper's open full text with the passage quoted, self-citation stacks, and a signed report. Each model call has its own
signed receipt. Use only what is listed below. If you need something else, stop and ask me.

- Base URL: `https://api.decosa.ai`
- Health check: `GET https://api.decosa.ai/healthz`.
- The hosted API is for published papers, your own drafts and testing your integration. A manuscript under peer review
  is confidential: for that, use the self-host prompt instead.
- It is a screening aid, not a finding of misconduct. Show every flag as something for a person to check.

## Auth: API key (or a demo session)
1. Preferred: an API key (`dk_…`) from "Get an API key" on the tool page. Keep it in an environment variable,
   `DECOSA_API_KEY`, never in code. Send `Authorization: Bearer $DECOSA_API_KEY`.
2. Without a key: `POST https://api.decosa.ai/demo/session` with `{"vertical": "paper-claim-check"}` returns `{"token", "expires_at", "budget"}`.
   a limited number of sessions per network per hour (the current limits are in `demo_sessions` of GET /healthz); each session has a token allowance (its `budget`) (about 110 checked citations). Over a limit: HTTP 429 with `Retry-After`.
3. One check at a time per demo token (409 otherwise).

## Endpoints
- `POST /papercheck/extract` (token) `{"filename": "paper.pdf", "file_b64": "..."}` → `{text, kind, references, citations, style, notes}`.
  PDF, DOCX, LaTeX, text; up to about 11 MB. PDF text loses superscript citation numbers; prefer DOCX or LaTeX.
- `POST /papercheck/check` (token). Body: `{"text": "...", "authors"?: ["Jane Smith", "Kim Lee"], "title"?: "...", "check_claims"?: true, "stream"?: true}`
  or `{"sample": "telecommuting-planted"}`.
  - The reference list goes at the end under a heading such as "References". Citations: `[3]`, `[3-5]`, `(3)` or
    author-year `(Smith et al., 2020)`.
  - Limits: 250,000 characters, 250 references, 60 checked citations per request (the rest come back `skipped`).
    `"check_claims": false` runs the reference checks only (no model call, no budget).
  - With `"stream": true` it streams `ready` (the text, citations and references with offsets), a `reference` event per
    reference, a `receipt` after each model call, a `claim` event per citation, then `report`, `done` and `budget`.
    With `"stream": false`: one JSON object `{run_id, text, citations, receipts, report, budget}`.
  - Claim verdicts: `supported`, `partial` (overstated or changed), `unsupported`, `contradicted`, `unavailable` (no open
    full text, or only an abstract that cannot settle it), `error`, `skipped`. Each has `evidence` (quoted passages),
    `reason`, `basis` and `receipt_ids`.
  - `report.issues`: `[{id, kind, severity: error|warning|note, message, ref?, claim?}]`; kinds include `retracted`,
    `expression_of_concern`, `corrected`, `doi_not_found`, `doi_mismatch` (with `suggested_doi`), `year_mismatch`,
    `author_mismatch`, `missing_reference`, `not_cited`, `self_citation_stack`, `claim`.
- `GET /papercheck/runs/{run_id}/export?format=md|json|record`.
- `POST /record/verify` (no token) `{"record": {...}}` → `{ok, summary, bad}`.
- `GET /papercheck/info`, `GET /papercheck/samples`, `GET /papercheck/samples/{id}`, `GET /attest/signing-key` (no token).

## Example: check a paper and print the flags (Python, `pip install httpx`)
```python
import httpx, os
API = "https://api.decosa.ai"
H = {"Authorization": f"Bearer {os.environ['DECOSA_API_KEY']}"}
text = open("paper.txt").read()                        # or POST /papercheck/extract for a PDF or DOCX
r = httpx.post(f"{API}/papercheck/check", headers=H, timeout=900,
               json={"text": text, "authors": ["Jane Smith"], "stream": False})
r.raise_for_status()
rep = r.json()["report"]
for x in rep["issues"]:
    if x["severity"] != "note":
        print(x["severity"], x["kind"], x["message"])
```

## Honest limits
- Only open-access cited papers are read; in our test papers 56% of citations had only an abstract or nothing, and
  those come back `unavailable`.
- About one flag in four on correct background citations is noise (measured 12 of 49); each flag quotes the passage.
- Retraction data comes from Crossref (with the Retraction Watch data) and OpenAlex and can lag the publishers.

Run it yourself (containers)

On request. The container images and the compose file aren’t public yet. Ask for self-host access and Decosa sends the registry (DECOSA_REGISTRY) and the compose file’s URL (DECOSA_COMPOSE_URL) these steps use. They are the steps we tested end to end on a fresh machine.

# Decosa citation and claim checker: run it yourself (containers)

You are setting up the Decosa citation and claim checker on this machine, so confidential manuscripts never leave it.
It checks every reference against Crossref and OpenAlex (retractions, corrections, wrong DOIs and years), every citing
sentence against the cited paper's open full text, flags self-citation stacks and signs a report. Only DOIs and
reference strings go to the public metadata services; nothing is sent to Decosa's hosted API.

Status: the container images (${DECOSA_REGISTRY}/decosa-*) and the compose file are on request while self-host is in early access (not on a public registry yet): ask at https://decosa.ai/contact?topic=self-host, and Decosa sends the registry as DECOSA_REGISTRY, the compose file URL as DECOSA_COMPOSE_URL, and pull access. If a pull fails with
"not found", "denied" or "unauthorized", stop and tell me. Do not substitute other images.

Ask me before any command that needs sudo, and show me the command first.

## Step 0: set up with a coding agent, rehearse on mock data, then go private

This prompt is for a coding agent running on the machine that will host the service. We recommend Claude Code with
Claude Opus 5.5; any capable coding agent works. Work in this order:

1. Set up on mock data only. During the whole setup you (the agent) work with the synthetic sample bundle below and
nothing else. Do not ask me for real data, and do not open, read, list or copy files that hold real data, even to
"test with something realistic".
2. Rehearse. When the steps below are done and the service is healthy, fetch the mock-data bundle for this tool,
https://decosa.ai/samples/paper-claim-check.zip (2 KB, 10 checks, synthetic or openly licensed: see `licence` in expected.json),
show me what is in it, and run the rehearsal against the local API:
`docker compose exec api python scripts/rehearse.py paper-claim-check` (the api image carries the same bundle under /app/rehearsal/paper-claim-check/;
with no key set, the script asks the local API for a short demo token). From a decosa-api checkout instead:
`python scripts/rehearse.py paper-claim-check --bundle paper-claim-check.zip --base-url http://127.0.0.1:<PORT>`.
It sends the mock inputs to the local API and prints PASS or FAIL for each expected property (for example: "four references are found", "citation [1] is supported with a quoted passage", "citation [2] is supported with a quoted passage"). Show me
the full output. Every check must pass. If one fails, fix the install and run it again; never edit `expected.json`
to make a check pass.
3. Stop there. Once the rehearsal passes, tell me, and I will run my own data against the local API myself, on this
machine.

For the person running this: a coding agent that runs in the cloud sees everything in its context, including files it
reads, command output and anything pasted into the chat. Keep real data out of the chat and out of anything the agent
can read. Switch to your own data only after the rehearsal has passed and the agent's work is done.

## Steps
1. Docker: if `docker compose version` fails, install Docker Engine and the compose plugin using Docker's official
instructions for this distribution (docs.docker.com/engine/install). Also install the NVIDIA container toolkit and
check `docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi`.
2. Fetch the compose file:
`mkdir -p ~/decosa && cd ~/decosa && curl -fsSL "${DECOSA_COMPOSE_URL}" -o compose.yaml`
Read it. Keep the `llm` service (Qwen3.8-27B on vLLM) and the `api` service; add `lfoppiano/grobid:0.8.2` as a
`grobid` service if I want better reference parsing. For the `api` service set `DECOSA_LLM_ROUTE=direct`,
`DECOSA_LLM_URL=http://llm:8000/v1`, `DECOSA_LLM_MODEL=qwen3.8-27b`, `DECOSA_PAPERCHECK_MAILTO=<my contact address>`
(ask me for it), `DECOSA_PAPERCHECK_GROBID_URL=http://grobid:8070` if GROBID is there, and bind every port to
127.0.0.1. The api needs outbound HTTPS to api.crossref.org, api.openalex.org, www.ebi.ac.uk, arxiv.org and doi.org.
3. Pull and start: `docker compose pull && docker compose up -d`. Wait for the `llm` health check (the first start
downloads about 20 GB of weights).
4. Check: `curl -fsS http://127.0.0.1:<PORT>/papercheck/info` shows `"route": "direct"` and my contact address in the
User-Agent; `GET /attest/signing-key` shows this box's public key. Show me the key: it is what others pin to verify
my reports.
5. Smoke test: get a token with `POST /demo/session {"vertical":"paper-claim-check"}` and run
`POST /papercheck/check {"sample": "telecommuting-planted", "stream": false}`. Expect reference 43 flagged retracted,
the `[36]` sentence `unsupported`, the `[42]` sentence `contradicted` with a quoted passage and a `year_mismatch` on
reference 1; every receipt `attested`. Then `POST /record/verify` with `report.record`: `ok` must be true.
6. Report back: the public key and key id, the totals, the flags and how long the run took.

Off, and keep it off on a box that holds confidential manuscripts: joining serves other people's requests on this GPU.
If I ask for it later, on a separate machine, follow the Provide page instead of improvising.

No NVIDIA GPU? Parts of this tool also run on an Apple Silicon Mac (MLX, 32 GB of unified memory or more): use https://decosa.ai/prompts/paper-claim-check-mac.md instead.

Run it on your own hardwareWhat it needs, and the prompt that sets it up

Run it on your own GPU

Same app, same pinned models, your hardware. Nothing goes to our servers and there are no Decosa charges.

Hardware check

Check your own hardware

CPU only, 64 GB RAMlite tierRuns with a smaller tier
The standard tier does not fit: Qwen3.8-27B (NVFP4) needs a GPU. The lite tier fits.
GeForce RTX 4090standard tierRuns
The standard tier fits with changes: Replace Qwen3.8-27B (NVFP4) with A community 4-bit build of Qwen3.8-27B (AWQ or GGUF). This build is NVIDIA NVFP4, which needs a Blackwell GPU. (Memory is an estimate.)
GeForce RTX 5090standard tierRuns
The standard tier fits with changes: Qwen3.8-27B (NVFP4): run it at its smallest setting (about 28 GB instead of 57.6 GB), with a shorter context and fewer parallel sessions.
2x GeForce RTX 5090standard tierRuns
The standard tier fits with changes: Split the language model across the GPUs with tensor parallelism (vLLM --tensor-parallel-size).
L40Sstandard tierRuns
The standard tier fits with changes: Replace Qwen3.8-27B (NVFP4) with Qwen3.8-27B official FP8. This build is NVIDIA NVFP4, which needs a Blackwell GPU.
H100 80 GB (SXM)standard tierRuns
The standard tier fits with changes: Replace Qwen3.8-27B (NVFP4) with Qwen3.8-27B official FP8. This build is NVIDIA NVFP4, which needs a Blackwell GPU.
RTX PRO 6000 Blackwell 96 GBstandard tierRuns
The standard tier fits (57.6 of 96 GB).
2x RTX PRO 6000 Blackwell 96 GBstandard tierRuns
The standard tier fits (57.6 of 192 GB).
Apple M3 Ultra (Mac Studio), 96 GBstandard tierRuns
The standard tier fits with changes: GROBID's image is amd64 only; on Apple Silicon it runs emulated (untested)
Apple M5 Max, 64 GBstandard tierRuns
The standard tier fits with changes: GROBID's image is amd64 only; on Apple Silicon it runs emulated (untested)

Memory per component comes from measured footprints, the tool's stack.json, or an estimate from its parameter count, and each is labelled that way below. Only an RTX PRO 6000 and an M3 Ultra Mac Studio have actually been run.

On request. The container images and the compose file aren’t public yet. Ask for self-host access and Decosa sends the registry (DECOSA_REGISTRY) and the compose file’s URL (DECOSA_COMPOSE_URL) these steps use. They are the steps we tested end to end on a fresh machine.

1
Check the GPU, Docker and the NVIDIA Container Toolkit
The driver must see the GPU, and Docker must be able to pass it into a container.
```
nvidia-smi
docker compose version
docker run --rm --gpus all ubuntu nvidia-smi
```
2
Fetch the compose file
One file describes the API and the language model as services.
```
mkdir -p ~/decosa && cd ~/decosa
curl -fsSL "${DECOSA_COMPOSE_URL}" -o compose.yaml
```
3
Pull and start
The first start downloads pinned model weights, tens of gigabytes.
```
docker compose pull
docker compose up -d
```

4

Check health

Wait until the API reports ok with the language model loaded. Then point your app at the local base URL.

curl -fsS http://localhost:<PORT>/healthz
# {"ok": true, "llm": true, ...}
curl -fsS -X POST http://localhost:<PORT>/demo/session \
  -H 'Content-Type: application/json' -d '{"vertical":"paper-claim-check"}'

Set up with a coding agent, rehearse on mock data, then go private

Set up with a coding agent. Paste the self-host prompt into a coding agent on the machine that will run the service. We recommend Claude Code with Claude Opus 5.5; any capable coding agent works.
Rehearse on mock data. The agent runs the tool on a bundle of synthetic inputs and checks each answer against the bundle's expected.json. Every check must print PASS.
Go private. Only then do you run your own data against the local API, yourself, on that machine. Never give the agent real data during setup: a coding agent that runs in the cloud sees everything in its context, so keep real data out of the chat and out of the files it reads.

Rehearsal command

docker compose exec api python scripts/rehearse.py paper-claim-check

Download the mock-data bundle (2 KB, 10 checks)expected.json

A four-sentence manuscript citing three papers from the reference list of an open-access CC BY article, plus the retracted 2020 hydroxychloroquine registry study. Citations [1] and [2] must be supported with a quoted passage, [3] (a hospital Staphylococcus aureus paper cited for SARS-CoV-2 super-spreaders) must be flagged, reference 4 must be flagged retracted, and the signed record must verify and catch a changed entry. Lookups go to Crossref, OpenAlex and Europe PMC.

What the rehearsal checks

four references are found
citation [1] is supported with a quoted passage
citation [2] is supported with a quoted passage
the wrong paper cited as [3] is flagged
reference 4 is flagged retracted
the retraction is raised as an error issue
the signed record verifies
a record with the [3] verdict changed to supported no longer verifies
verification points at a claim entry
every model call has a signed receipt

Licence: The sentences are written for Decosa; the three reference strings come from the reference list of Mauras S et al., PLoS Comput Biol 2021;17(8):e1009264 (CC BY 4.0), and reference 4 is the public bibliographic entry of Mehra et al., The Lancet 2020 (retracted). Part of decosa-api, AGPL-3.0-or-later.

Prompt for your coding agent