RegCheck API

HTTP API reference · v1

The RegCheck API lets you submit comparisons programmatically, poll their status, and retrieve structured results. A comparison runs asynchronously on a worker; you submit it, poll until it finishes, then fetch the result.

Authentication is required. Every /api/v1 request must send a RegCheck API key (issued by a signed-in account) as Authorization: Bearer rc_live_…. Create and manage keys on your profile. A key is shown once at creation; only its hash is stored. Reports created or read via the API are scoped to the owning account.

1) Base URL & flow

All paths are under the site origin, e.g. https://<your-regcheck-host>/api/v1. A typical run:

Submit POST /api/v1/compare → returns 202 with a JSON task_id and links.
Poll GET /api/v1/status/<task_id> until state is "SUCCESS" or "FAILURE".
Fetch GET /api/v1/reports/<task_id> for the structured result (or open view_url for the interactive report).

2) Submit a comparison

POST /api/v1/compare

Content type: multipart/form-data. Provide a preregistration file for a general comparison, or set clinical_registration=yes with a registration_id for a ClinicalTrials.gov registration.

Field	Required	Description
`dimensions_data`	cond.	JSON array of the dimensions to compare (see below). Provide this or `dimension_set`.
`dimension_set`	cond.	A built-in discipline preset to use instead of `dimensions_data` — the same sets the web app offers: `psychology`, `clinical`, `economics`, or `preclinical`. Provide this or `dimensions_data` (not both).
`paper`	yes	The published paper file (`.pdf`, `.docx`, `.txt`, or `.html`).
`preregistration`	cond.	The preregistration file (`.pdf`, `.docx`, `.txt`, or `.html`). Required unless `clinical_registration=yes` or an `osf_url` is given.
`osf_url`	cond.	An OSF link (e.g. `https://osf.io/abc12/`) used as the preregistration instead of a file — resolves either an OSF registration (its form responses) or a hosted file (downloaded & processed).
`clinical_registration`	no	`yes`/`no` (default `no`). When `yes`, fetches a ClinicalTrials.gov registration from `registration_id`.
`registration_id`	cond.	ClinicalTrials.gov identifier (e.g. `NCT01234567`). Required when `clinical_registration=yes`.
`visibility`	no	`private` (default) or `public`. Public reports are listed on your public profile and viewable by anyone with the link; private reports are viewable only by you and the people you grant access to by email or ORCID iD (manage grantees in the web app). The API only ever returns your own reports regardless of visibility.
`client`	no	Model provider, with the exact default model in parentheses (overridable server-side): `openai` (ChatGPT — `gpt-5.5`; default), `claude` (Claude Opus 4.8 — `claude-opus-4-8`), `deepseek` (`deepseek-reasoner`), or `qwen` (Qwen3.6 27B via Groq — `qwen/qwen3.6-27b`).
`parser_choice`	no	`pymupdf` (default; in-process, keeps all text), `grobid` (typeset PDFs), or `dpt2` (OCR / non-standard docs).
`reasoning_effort`	no	Optional reasoning-effort hint where supported.
`append_previous_output`	no	`yes`/`no`. When `yes`, earlier dimension responses are included as context for later ones.
`multiple_experiments`, `experiment_number`, `experiment_text`	no	For papers reporting multiple studies, narrow the analysis to a single study (the parameter names are kept for API stability).

The `dimensions_data` field

A JSON-encoded array of objects, each with a dimension name and an optional definition. Order is preserved; at least one is required. To use one of the web app's built-in presets instead, send dimension_set (e.g. dimension_set=psychology) and omit dimensions_data.

[
  { "dimension": "Sample size", "definition": "The planned or realised number of participants…" },
  { "dimension": "Hypotheses", "definition": "The specific, directional predictions stated before data collection…" }
]

Example

curl -X POST https://<host>/api/v1/compare \
  -H "Authorization: Bearer rc_live_xxxxxxxx" \
  -F 'dimensions_data=[{"dimension":"Sample size","definition":""}]' \
  -F "preregistration=@prereg.pdf" \
  -F "paper=@paper.pdf"

# → 202 Accepted
# {
#   "task_id": "…", "state": "PENDING",
#   "status_url": "https://<host>/api/v1/status/…",
#   "report_url": "https://<host>/api/v1/reports/…",
#   "view_url":   "https://<host>/result/…"
# }

3) Poll status

GET /api/v1/status/<task_id>

{
  "task_id": "…",
  "state": "SUCCESS",            // PENDING | IN_PROGRESS | SUCCESS | FAILURE
  "status": "Complete",
  "processed_dimensions": 5,
  "total_dimensions": 5,
  "title": "smith et al 2024",
  "visibility": "private"
}

4) Fetch the result

GET /api/v1/reports/<task_id>

{
  "task_id": "…", "title": "…", "visibility": "private", "state": "SUCCESS",
  "result": {
    "items": [
      {
        "dimension": "Sample size",
        "deviation_judgement": "yes",   // "yes" | "no" | "missing"
        "deviation_information": "…",
        "registration_content_summary": "…",
        "paper_content_summary": "…",
        "registration_content_quotes": "[PREREG_0001, relevance_score=0.94] …",
        "paper_content_quotes": "[PAPER_0001, relevance_score=0.93] …"
      }
    ]
  }
}

5) Manage your reports

GET /api/v1/reports — list your reports (id, title, visibility, type, created-at, links).
DELETE /api/v1/reports/<task_id> — permanently delete a report you own.
For the interactive, highlighted report, open view_url (/result/<task_id>) in a browser.

6) Errors & notes

401 — missing/invalid/revoked API key. Send Authorization: Bearer rc_live_….
404 — the report does not exist or is not owned by your key's account.
Processing is asynchronous (worker + Redis + the selected model provider). Quote strings carry chunk IDs (PREREG_0001/PAPER_0001) with cosine-similarity scores.
Source & issues: GitHub. See also the Privacy Policy for data handling and retention.