API v2 (beta): the review as a letter
The v2 beta returns a review the way ReviewerZero's own Feedback view presents it to an editor: one section per dimension, numbered points inside each section (PR.1, REF.2), and under each point the findings it stands over. Every dimension has the same keys, every point the same keys, every finding the same keys, so a consumer maps the shape once and renders any dimension the same way.
dimensions carries the checks that ran on this manuscript. A check that was not enabled is left out rather than returned as an empty row. The id set is fixed for this version, so if you need to show what was skipped, subtract the ids you received from the ten listed below.
This is a beta: while it carries the _beta suffix the shape can still change, and we will tell you before it does. Once it settles, changes come with a new version.
Authentication
Same as v1: Authorization: Bearer <api key> on every request.
Submitting a manuscript
POST /api/v2_beta/reviews accepts exactly the fields of POST /api/v1/reviews, payload_detail included. The only difference is the callback: a review submitted here delivers its review.completed callback in the v2 shape below.
Fetching results
curl "https://www.reviewerzero.ai/api/v2_beta/reviews/proj_a1b2c3d4e5" \
-H "Authorization: Bearer $REVIEWERZERO_API_KEY"As in v1, payload_detail=issues_only (the default) lists only the points that need review; payload_detail=full adds the suggestions:
curl "https://www.reviewerzero.ai/api/v2_beta/reviews/proj_a1b2c3d4e5?payload_detail=full" \
-H "Authorization: Bearer $REVIEWERZERO_API_KEY"The per-dimension counts are complete at either level.
Response
{
"api_version": "v2_beta",
"review_id": "proj_a1b2c3d4e5",
"payload_detail": "full",
"status": "finished",
"title": "On the Selective Relation of Frontal Cortical Asymmetry and Anger-Out Versus Anger-Control",
"report_url": "https://www.reviewerzero.ai/app/review/proj_a1b2c3d4e5",
"dimensions": [
{
"id": "statistics",
"label": "Statistics",
"status": "has_issues",
"summary": { "total": 110, "needs_review": 2, "suggestions": 32, "description": "110 statistics · 34 flagged findings" },
"issues": [
{
"code": "STAT.1",
"title": "Clarify the significance of 2 statistical results",
"severity": "high",
"description": "Automated recalculation differs from the reported p-values for the listed results.",
"findings": [
{
"location": "p. 8",
"quote": "r = .22, p = .049",
"description": "Reported p = 0.049 recomputes to p = 0.097. The reported p = 0.049 does not follow from the reported r = 0.22, which gives p = 0.097."
},
{
"location": "p. 9",
"quote": "r = -.23, p = .039",
"description": "Reported p = 0.039 recomputes to p = 0.0797. The reported p = 0.039 does not follow from the reported r = -0.23, which gives p = 0.0797."
}
]
}
]
},
{
"id": "references",
"label": "References",
"status": "has_issues",
"summary": { "total": 106, "needs_review": 0, "suggestions": 14, "description": "106 references · 14 flagged findings" },
"issues": [
{
"code": "REF.1",
"title": "Correct 7 reference records",
"severity": "medium",
"description": "The listed references contain bibliographic discrepancies against the matched records. The individual comparisons support a single correction request.",
"findings": [
{
"location": "p. 12",
"quote": "Cohen, J., & Cohen, P. (1983). Applied multiple regression/correlation analysis for the behavioral sciences. Hillsdale, NJ: Erlbaum.",
"description": "Reference 14. The author list differs from the published record (the record adds Tufte). Published record: https://doi.org/10.2307/2286442"
}
]
}
]
}
]
}The example is abridged: a real response lists every check that ran and every point under it.
Fields
| Field | Description |
|---|---|
payload_detail | issues_only (only red points listed, default) or full (red and amber). |
dimensions[] | One section of the letter, for each check that ran, in letter order. The id set for this version is authors, figures, statistics, tables, peer-review, references, ai-text, plagiarism, replicability, guidelines; a check that did not run is absent. |
dimensions[].status | has_issues, no_issues (ran, nothing to flag), in_progress (analysis still running), no_result (ran, returned nothing). A check that did not run has no entry at all, so no_issues always means the manuscript was actually checked. |
dimensions[].summary | total: items examined, in the check's own unit (106 references, 0 figures, 31 peer-review points; null when the check did not run). It is not a denominator: one item can raise several findings, and some checks flag values that are not among the items counted, so a dimension can report more flagged findings than items examined: a figure that matches an image on the web and has low contrast is two findings, one under each point. needs_review: red entries under the points. suggestions: amber entries. description: one line on what was examined and how it came out; its flagged total is needs_review + suggestions. Green items are never returned. |
dimensions[].issues[] | One numbered point of the letter (REF.1). Groups the findings that share one request, such as several reference records to correct or several p-values to reconcile. Numbering restarts per dimension. |
issues[].severity | high (needs review) or medium (a suggestion): the worst of its findings. With payload_detail=issues_only only high points appear, regrouped from the red findings alone. |
issues[].description | The point as written to the editor: the request, followed by any caveat the check attaches to it, separated by a blank line. |
issues[].findings[] | One entry under the point, in three keys: location (p. 12 (Data Analysis)), quote (the manuscript's own words, and only those: the reference as printed, the statistic as printed, the passage; null when the check filed none), and description, the rest of what the letter says about the entry as one piece of text: what names it (Reference 14), what is wrong with it, the venue rule it does not meet, and any links, each as Label: URL. A name the point's own title already gives is not repeated. |
Contract
- Every dimension, point and finding has every key above; a key with no value is
null, never absent. - The set of dimension ids is fixed for this version. Which of them a response carries depends on which checks ran; one that carries findings is always present.
- A review whose files have not been processed still answers, and still sends its callback, rather than returning a 404 or leaving a webhook unsent. Its checks come back
no_result, orin_progresswhile the analysis is still running.dimensionsis empty only when no check was enabled for the submission. - Only flagged findings are returned: red at
issues_only, red and amber atfull. Green items and findings dismissed in ReviewerZero are never listed, andneeds_review,suggestionsand thedescriptionline all exclude the dismissed ones.totalcounts everything the check examined.
Callback
A review submitted through POST /api/v2_beta/reviews with a callback_url receives one POST when analysis completes, with the response above (at the payload_detail given on submission) plus "event": "review.completed" and "timestamp". Headers and signature are as in v1 (Verifying the Callback Signature), with one addition:
| Header | Value |
|---|---|
X-ReviewerZero-Api-Version | v2_beta |