Checks API
Read approved public records, run local checks, or contribute a documented private draft with your account or a scoped Checks API key.
Public records and private drafts have separate boundaries. Anonymous reads return only fields approved for public disclosure. Authenticated contribution routes store private, owner-scoped records. Uploading a draft does not make it public or establish independent scientific review. The live OpenAPI contract describes both surfaces.
Read approved public records
Search by DOI or PMID on the homepage, or browse the approved catalogue. Public lookup does not search restricted submissions. A missing result means no approved public record was returned; it is not a pass or a statement that the paper has never been checked.
The public API base is https://api.evidence.guide/checks/v1/public. These reads require no user authentication. Use a typed scheme of doi or pmid and a matching value. PMID values use nonzero-leading digits only. Identifier associations are source-reported; lookup does not establish DOI–PMID equivalence, and cited references do not become aliases for the checked paper.
# Public read: no user token, API key or browser cookie.
PUBLIC_CHECKS="https://api.evidence.guide/checks/v1/public"
curl --fail-with-body --get "$PUBLIC_CHECKS/identifier-checks" \
--header "Accept: application/json" \
--data-urlencode "scheme=pmid" \
--data-urlencode "value=36909407"| Method and path | Purpose |
|---|---|
| GET /identifier-checks?scheme=…&value=… | Find approved records by DOI or PMID. |
| GET /snapshot | Read the current approved catalogue. |
| GET /changes | Read ordered approval and withdrawal events. |
| GET /publications/{publication_id} | Read a public record by its public publication identifier. |
List reads accept limit from 1–100 (default 50) and the opaque cursor returned by the service. Keep cursors tied to their operation and query; on a conflict or expired cursor, start a fresh read. Responses are no-store. Respect Retry-After on 429; the site does not start background polling or crawling.
The current source-assertion profile uses approved-public-identifiers/3 records, with approved work identifiers, source credit and a source-reported assertion. Snapshot and change wrappers have their own explicit versions. Public publication IDs are separate from private check, case and revision IDs. Preserve the returned source attribution, license and modification notice, coverage and machine/human review status.
The included service also supports https://paper-checks-api-mshsk.ondigitalocean.app/checks/v1/public and the compatibility base https://paper-checks-api-mshsk.ondigitalocean.app/v1/public. It remains an explicit operator-selected rollback option; clients should not automatically retry against another origin. Existing extraction https://api.evidence.guide/v1 is separate from the permanent Checks namespace https://api.evidence.guide/checks/v1.
Two ways to contribute a check
Start with local browser checks
Open Run local checks, choose the fictional sample or a local UTF-8 text file, select the checks, and confirm your source rights and processing permissions. The current browser tools inventory reported p-values and document/DOI candidates. They run locally and keep a private draft in page memory.
Inspect the result, its scope and source pointers before exporting. statcheck support imports an existing report; it does not execute statcheck. The scrutiny package panel prepares requests for a separate approved local runner; package execution is not connected in the browser.
Upload results from a script or another tool
Prepare a check record in the exchange format below, then submit it with your own session token or a Checks API key with checks:submit, and a unique idempotency key. This API stores a check record; uploading a record does not run a checker, retrieve a paper or start a model review.
Browser export and API record are different formats. A private audit export, package-runner envelope or imported statcheck draft cannot be posted unchanged. Review and map it into the 0.3-draft check-record format first. The local audit does not upload its draft automatically.
Authorized accounts can also use Private checks to look up their own records, inspect an ingestion receipt, preview native JSON and submit a restricted record when their permissions allow it. The workspace reads current capabilities from the service; signing up alone does not grant contribution access. A request outcome that is not confirmed requires reconciliation rather than an automatic retry.
Use your own credential and operation permissions
Sign in to your own Evidence Guide account. In that signed-in browser session, the session-token endpoint returns an accessToken value for API clients. Use the token value as Authorization: Bearer <USER_ACCESS_TOKEN>; do not send the surrounding JSON object.
The checks service independently verifies the user session and checks an operator-managed permission grant. You need contributor access to submit or preview records. A valid account or new signup alone does not grant upload permission; a reader can only read their own records. For scripts, a scoped Checks API key can replace the session token on data endpoints. It cannot grant permissions that your account does not currently hold.
Session tokens and Checks API keys are separate from extraction API keys, provider/model keys and Supabase project keys. Do not share credentials in chat, repositories, URLs or logs. Keep them out of checker inputs and provider plugins. When a session expires, refresh through the normal Evidence Guide sign-in flow; Checks API keys have their own expiry and revocation lifecycle.
401 means authentication is missing or invalid. 403 means the verified account lacks the required checks grant. 503 can mean verification or storage is unavailable; it does not mean the token should be replaced with an administrator key.
Use a scoped Checks API key for automation
Checks API keys use the same Authorization: Bearer <CHECKS_API_KEY> header on data endpoints. The available scopes are checks:read, checks:submit and checks:preview. Choose only the operations your script needs. Reads remain limited to your own submissions; a read-only key cannot upload, preview, manage keys or read another contributor’s records.
Key management requires a verified user session JWT and the separate server-assigned keys:manage grant. Contributor or reader access does not include key management automatically. A Checks API key cannot issue, list, revoke or rotate keys. The extraction dashboard manages extraction keys; Checks keys use the separate API below, not that dashboard.
Create and manage a key with the API
Using the operator-confirmed base, send POST /api-keys with your session JWT and a canonical UUID4 Idempotency-Key. The request below grants submission only; add read or preview only when needed and permitted. Do not include account or owner fields.
{
"name": "My check uploader",
"scopes": ["checks:submit"],
"expires_in_days": 30
}Key lifetimes are 1–90 days, with a 90-day default. The default active-key cap is five per account and may be configured lower. Management idempotency keys must be canonical UUID4 values; record-upload idempotency keys have the different 1–200-character contract below.
The first successful create or rotate returns 201, with the complete credential in secret, secret_available: true and replayed: false. Save it directly to your own secret store without logging or sharing the response. A confirmed retry returns 200 with secret: null, secret_available: false and replayed: true; the secret cannot be recovered.
GET /api-keys lists your own key metadata. POST /api-keys/{key_id}/revoke revokes an owned key idempotently. POST /api-keys/{key_id}/rotate atomically replaces and revokes it, with a new canonical UUID4 operation key; its body may narrow scopes and set expires_in_days. Rotation cannot widen the original scope ceiling.
If a create or rotate response is lost, sign in normally, inspect your key list, and revoke the affected key before creating a new one. Rotation may have revoked the old key even if its response was lost. Do not blindly retry under a new operation ID or expect an idempotent replay to reveal the secret.
Keys have no refresh token. Expired, revoked or account-invalidated keys fail authentication; browser logout alone does not revoke them. Revocation prevents later authentication checks after commit, and does not cancel work already authenticated. Scope checks also enforce your current server-owned account grants.
Upload a new check record
The example uses the supported private service base https://paper-checks-api-mshsk.ondigitalocean.app/v1. Use your own granted contributor access. The permanent contract also uses https://api.evidence.guide/checks/v1; confirm protected-route availability with your operator before changing an upload client. Verified anonymous public reads do not establish authenticated upload availability. Public-read URLs are not upload routes.
Save a reviewed record using the record format below as check.json. Send it as JSON to POST /checks, with a fresh Idempotency-Key for that contribution. Use the same key and unchanged record when retrying an uncertain submission.
# Bash. Private record API; separate from anonymous public reads.
CHECKS_API="https://paper-checks-api-mshsk.ondigitalocean.app/v1"
# Read your own session token or Checks API key without placing it in shell history.
set +x
read -r -s -p "Evidence Guide session token or Checks API key: " CHECKS_CREDENTIAL
printf '\n'
# The header travels through stdin, rather than a literal token in curl arguments.
if [[ "$CHECKS_CREDENTIAL" =~ ^[A-Za-z0-9_-]+[.][A-Za-z0-9_-]+[.][A-Za-z0-9_-]+$ ]] ||
[[ "$CHECKS_CREDENTIAL" =~ ^pcd_pat_v1_[0-9a-f]{32}_[A-Za-z0-9_-]{43}$ ]]; then
printf 'header = "Authorization: Bearer %s"\n' "$CHECKS_CREDENTIAL" |
curl --fail-with-body --config - \
--request POST "$CHECKS_API/checks" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: replace-with-a-unique-run-id" \
--data-binary @check.json
else
printf 'Expected a session JWT or Checks API key value, without surrounding JSON.\n' >&2
fi
unset CHECKS_CREDENTIALA new record returns 201; an unchanged duplicate returns 200 with duplicate: true. Reusing the key with different content returns 409. Keys are scoped to your contributor identity and contain 1–200 characters. A new run needs a new identity; changing the key must not disguise a correction to an existing source record.
Preview validation before writing
POST /checks/bulk/dry-run accepts 1–100 entries. Each entry contains exactly idempotency_key and record. It reports accepted, duplicate, rejected or conflict outcomes without storing records. A successful preview is not a publication approval or guarantee that a later write cannot conflict.
# Build a preview envelope from your reviewed check.json.
python3 - <<'PY'
import json
from pathlib import Path
record = json.loads(Path("check.json").read_text())
preview = {"entries": [{
"idempotency_key": "replace-with-a-unique-run-id",
"record": record
}]}
Path("preview.json").write_text(json.dumps(preview))
PY
# Use the same private token-input/header pattern as the upload example.
# POST preview.json to: $CHECKS_API/checks/bulk/dry-run
# Body: {"entries": [{"idempotency_key": "...", "record": {...}}]}Read the submission receipt
Illustrative response only. Retain the actual check/revision identifiers and digest returned by the service; they are distinct from paper and input hashes.
{
"check_id": "00000000-0000-4000-8000-000000000001",
"revision_id": "00000000-0000-4000-8000-000000000002",
"number": 1,
"visibility": "restricted",
"digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"duplicate": false
}Describe what was checked and what is known
The exchange record uses schema_version: 0.3-draft. The current server validates its bounded V1 ingestion profile v4. Required top-level fields are schema_version, targets, check, provenance, execution, result and license.
This entire example is fictional. Replace its DOI, producer, method, version, dates, evidence and license with your actual contribution. It demonstrates an inconclusive machine report; it is not evidence that a real checker ran or a record was accepted.
{
"schema_version": "0.3-draft",
"targets": [
{ "id": "paper", "kind": "work", "doi": "10.0000/example.001" }
],
"check": {
"family": "statistical_consistency",
"method": { "name": "Fictional reporting check" },
"target_refs": ["paper"],
"coverage": "One selected statement in a fictional example; no whole-paper assessment."
},
"provenance": {
"mode": "automated",
"producer": { "name": "Fictional example contributor" },
"performed_at": "2026-11-09",
"components": [
{
"kind": "tool",
"name": "Fictional example checker",
"version": "0.1.0",
"version_status": "reported"
}
]
},
"execution": { "status": "completed" },
"result": {
"outcome": "inconclusive",
"summary": "This fictional example cannot resolve the selected statement.",
"findings": [],
"evidence": [
{
"status": "available",
"role": "method_output",
"text": "Synthetic report: the available statement does not provide enough context."
}
]
},
"license": "https://example.invalid/check-record-license"
}- Identify the work and the exact document or input version when known. Keep source locations, hashes and evidence pointers distinct from a DOI.
- State the method, target references, examined scope, limitations and uncertainty. Missing coverage is not complete coverage.
- Use
provenance.modeto distinguish automated, human, hybrid or unknown production. A machine finding or human upload does not establish independent human review. - The producer, optional performed-by agents and source origin are source-reported attribution. They are not verified identities. The server records the authenticated ingestor separately in its private ingestion receipt; uploading someone else’s result does not make you its checker.
- Record tool/model releases in
provenance.components. Optional exact toolcommitandcommit_urlare separate; omit them when unknown. A commit hash must be a full 40- or 64-character hexadecimal value. - Use a null version and a matching
provenance.missingexplanation when a component version is unknown. Do not invent a version from its tool URL or commit. - Keep execution state separate from the outcome.
not_runor failed execution isnot_assessed, with a reason.flags_reportedneeds findings; no flags is never an overall pass. - Retain method output and source evidence. A completed no-flags report requires affirmative available report evidence; an empty findings list alone is insufficient.
- Supply the actual record license reference and respect separate rights for papers, excerpts and provider output. Structural validation does not verify those rights.
Replication-family records and explicit replication-certification data are outside the current V1 ingestion profile. The API does not issue safety certificates, trust scores or scientific endorsements.
Private contribution API reference
These paths are relative to the private native base ending in /v1. They are separate from anonymous /checks/v1/public reads. Existing extraction /v1 contracts and keys remain separate.
| Method and path | Purpose | Permission |
|---|---|---|
| POST /checks | Create a restricted check-record draft; requires Idempotency-Key. | checks:submit |
| POST /checks/bulk/dry-run | Validate and preview 1–100 records without writing. | checks:preview |
| GET /checks?doi=… | DOI lookup within your own submissions; limit 1–100, default 50. | checks:read |
| GET /identifier-checks?scheme=…&value=… | Typed DOI/PMID lookup within your own submissions; identifier associations are source-reported. | checks:read |
| GET /checks/{check_id} | Read your own record and current revision. | checks:read |
| GET /checks/{check_id}/ingestion | Read the private authenticated-ingestor receipt, when recorded. | checks:read |
| POST /api-keys | Issue an owned scoped key; UUID4 Idempotency-Key; secret revealed once. | Session JWT + keys:manage |
| GET /api-keys | List your own key metadata; no secrets. | Session JWT + keys:manage |
| POST /api-keys/{key_id}/revoke | Idempotently revoke an owned key. | Session JWT + keys:manage |
| POST /api-keys/{key_id}/rotate | Replace and revoke an owned key; UUID4 Idempotency-Key. | Session JWT + keys:manage |
Data endpoints accept a session JWT or Checks API key and require the corresponding operation grant; a key is additionally limited by its scopes. Management endpoints accept session JWTs only. Another owner’s identifier returns 404. Invalid records return 422; excessive request bodies return 413. The default request limit is 1 MiB and the default quota is 120 requests per minute per contributor, with a separate default limit of 60 requests per minute per key; these limits are operator-configurable. On 429, honor Retry-After. Private responses are no-store.
The contribution endpoints do not provide bulk writes or an implicit correction/publication action. An upload does not overwrite an earlier revision. An explicit source-system/source-record pair is contributor-scoped: unchanged reimports are duplicates, while changed content conflicts rather than silently replacing the original.
Uploading is separate from publication
The server assigns every new submission visibility: restricted. Private reads remain owner-scoped. Uploading a check does not add it to the public homepage, publish source material or authorize redistribution.
Public disclosure uses a separate, permission-gated Publication review workflow bound to an exact source revision, rights declaration and approved field preview. Authorized reviewers can approve selected fields or withdraw their public disclosure. Neither a normal contributor grant nor a scoped Checks API key grants moderation authority.
Review the exact draft, source rights, private data, provider-output terms and proposed public fields before that separate decision. Disclosure approval is distinct from independent scientific review. Public reads expose only the approved projection, not the source record or private review case.
Provider hooks coming soon
Planned assistant workflows and provider connections could help produce and refine check records. The services below are integration targets; they are not connected and no partnership is implied.
- ClaudePlanned
Hooks for model-assisted paper analysis through Anthropic’s API, with a reviewable record of the method, inputs and output.
- ChatGPT / OpenAIPlanned
Workflows for bringing model-generated analysis into check records. OpenAI API access and billing are separate from a ChatGPT subscription.
- RefineTerms review
A paper-review integration target, subject to provider access, applicable terms, output rights and a reviewed adapter. No connector is enabled here.
- Reviewer3Access review
An integration target that needs provider access and a reviewed evidence.guide adapter. No connector is enabled here.
- ReviewerZeroPlanned
A review-provider API target. Its own provider credentials and document-upload permissions would be separate from an evidence.guide access token.
Each connection needs a reviewed adapter, provider access, source rights, explicit upload and cost permission, and a private-result review step. A provider’s machine critique is not independent human review and does not authorize publication.
See Refine’s API terms and OpenAI’s separate API billing guidance. Keep provider credentials separate from your evidence.guide token.