REST Resource: documents.reviews

Resource: Review

An evaluation run of a document.

JSON representation
{
  "name": string,
  "state": enum (State),
  "result": {
    object (Result)
  },
  "createTime": string,
  "startTime": string,
  "endTime": string,
  "runConfig": {
    object (DeepReviewRunConfig)
  },
  "progressPercent": integer
}
Fields
name

string

Identifier. Resource name in format documents/{document}/reviews/{review}.

state

enum (State)

Output only. Current review lifecycle state.

result

object (Result)

Output only. Review output (markdown, errors, and future modalities).

createTime

string (Timestamp format)

Output only. Timestamp when this review attempt was initiated.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

startTime

string (Timestamp format)

Output only. Timestamp when the worker started evaluation.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

endTime

string (Timestamp format)

Output only. Timestamp when the review reached a terminal state.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".

runConfig

object (DeepReviewRunConfig)

Optional. Run configuration parameters used for this review.

progressPercent

integer

Output only. Estimated completion progress percentage of the review in [0, 100].

Result

Encapsulates the synthesized output or failure details of a single review execution.

JSON representation
{
  "reviewMarkdown": string,
  "error": {
    object (Status)
  },
  "anchoredComments": [
    {
      object (AnchoredReviewComment)
    }
  ]
}
Fields
reviewMarkdown

string

Output only. Synthesized review report markdown.

error

object (Status)

Output only. Failure status details if review execution failed.

anchoredComments[]

object (AnchoredReviewComment)

Output only. Structured review comments anchored to specific locations in the document. At most 300 anchored comments are returned per review.

AnchoredReviewComment

A structured review comment anchored to a specific location in the document.

JSON representation
{
  "commentId": string,
  "severity": enum (Severity),
  "summary": string,
  "bodyMarkdown": string,
  "suggestedEdit": string,
  "location": {
    object (DocumentLocation)
  },
  "citationReport": {
    object (CitationReport)
  }
}
Fields
commentId

string

Output only. Unique identifier for the comment within the review.

severity

enum (Severity)

Output only. Severity classification of the comment.

summary

string

Output only. Short one-line summary of the review comment.

bodyMarkdown

string

Output only. Detailed markdown explanation of the review comment.

suggestedEdit

string

Output only. Optional suggested replacement text or edit for the anchored span.

location

object (DocumentLocation)

Output only. Polymorphic location in the document where this comment is anchored.

citationReport

object (CitationReport)

Output only. Optional structured citation verification report when this comment corresponds to a bibliography reference.

Severity

Severity level for an anchored review comment.

Enums
SEVERITY_UNSPECIFIED Default unspecified severity.
CRITICAL Critical flaw in proofs, methodology, or empirical claims.
MAJOR Major issue affecting key conclusions or experimental validity.
MINOR Minor issue, presentation clarity, or missing detail.
SUGGESTION Constructive suggestion or optional improvement.

DocumentLocation

A location targeting either a PDF page region/quote or text lines in the document.

JSON representation
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "pdf": {
    object (PdfLocation)
  },
  "text": {
    object (TextLocation)
  }
  // End of mutually exclusive fields.
}
Fields
The specific document location target. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response:
pdf

object (PdfLocation)

Output only. Location within a rendered PDF document.

text

object (TextLocation)

Output only. Location within a plain-text, Markdown, or LaTeX source document.

End of mutually exclusive fields.

PdfLocation

Location anchor within a PDF document.

JSON representation
{
  "pageNumber": integer,
  "quoteSelector": {
    object (TextQuoteSelector)
  },
  "boundingBoxes": [
    {
      object (NormalizedBoundingBox)
    }
  ]
}
Fields
pageNumber

integer

Output only. 1-indexed page number within the PDF document.

quoteSelector

object (TextQuoteSelector)

Output only. W3C Web Annotation TextQuoteSelector (https://www.w3.org/TR/annotation-model/#text-quote-selector) for exact text span highlighting.

boundingBoxes[]

object (NormalizedBoundingBox)

Output only. Normalized bounding boxes [0.0, 1.0] relative to page width and height. At most 50 bounding boxes are returned per anchored span.

TextQuoteSelector

W3C Web Annotation TextQuoteSelector for resilient text anchoring (see https://www.w3.org/TR/annotation-model/#text-quote-selector for details).

JSON representation
{
  "exact": string,
  "prefix": string,
  "suffix": string
}
Fields
exact

string

Output only. Verbatim substring extracted from the document character stream.

prefix

string

Output only. Characters immediately preceding exact for disambiguation.

suffix

string

Output only. Characters immediately following exact for disambiguation.

NormalizedBoundingBox

Bounding box in normalized [0.0, 1.0] page coordinates (origin top-left).

JSON representation
{
  "left": number,
  "top": number,
  "right": number,
  "bottom": number
}
Fields
left

number

Output only. Left coordinate in [0.0, 1.0].

top

number

Output only. Top coordinate in [0.0, 1.0].

right

number

Output only. Right coordinate in [0.0, 1.0].

bottom

number

Output only. Bottom coordinate in [0.0, 1.0].

TextLocation

Location anchor within a plain-text, Markdown, or LaTeX source document.

JSON representation
{
  "firstLine": integer,
  "lastLine": integer,
  "firstColumn": integer,
  "lastColumn": integer,
  "quotedLinePreview": string
}
Fields
firstLine

integer

Output only. 1-indexed inclusive first line number.

lastLine

integer

Output only. 1-indexed inclusive last line number.

firstColumn

integer

Output only. Optional 1-indexed inclusive first column offset within firstLine.

lastColumn

integer

Output only. Optional 1-indexed inclusive last column offset within lastLine.

quotedLinePreview

string

Output only. Verbatim snippet of the anchored source line(s).

CitationReport

Structured citation verification report for a single bibliography reference.

JSON representation
{
  "refNum": integer,
  "rawReference": string,
  "citationKey": string,
  "entryType": string,
  "finalVerdict": enum (Verdict),
  "lookupVerdict": enum (Verdict),
  "searchVerdict": enum (SearchVerdict),
  "searchMethod": string,
  "extractedMetadata": {
    object (CitationMetadata)
  },
  "retrievedMetadata": {
    object (CitationMetadata)
  },
  "retrievedBibtex": string,
  "fieldComparisons": [
    {
      object (FieldComparison)
    }
  ],
  "firstAuthorFamilyNameMatch": boolean,
  "searchRationale": string,
  "groundingUrls": [
    {
      object (GroundingUrl)
    }
  ]
}
Fields
refNum

integer

Output only. 1-indexed bibliography reference number in the paper.

rawReference

string

Output only. Verbatim reference string extracted from the paper's bibliography.

citationKey

string

Output only. Generated BibTeX citation key (e.g., "smith2023deep").

entryType

string

Output only. BibTeX entry type (e.g., "article", "inproceedings", "misc").

finalVerdict

enum (Verdict)

Output only. Final combined verdict after database lookup and search grounding.

lookupVerdict

enum (Verdict)

Output only. Verdict from scholarly database lookup (OpenAlex / Crossref) before search grounding.

searchVerdict

enum (SearchVerdict)

Output only. Verdict from Google Search grounding verification (when run).

searchMethod

string

Output only. Strategy that produced the scholarly database match (e.g., "doi", "title", "title_author", "autocomplete"). Empty when no title-matching candidate was found.

extractedMetadata

object (CitationMetadata)

Output only. Metadata parsed from the paper's bibliography entry.

retrievedMetadata

object (CitationMetadata)

Output only. Metadata retrieved from OpenAlex / Crossref. Populated only when the retrieved work's title matches the extracted title. Omitted when no candidate matches the title so unrelated papers are never displayed as candidates.

retrievedBibtex

string

Output only. Formatted BibTeX entry for the verified retrievedMetadata when present. Empty when retrievedMetadata is absent.

fieldComparisons[]

object (FieldComparison)

Output only. Per-field comparisons (populated only when retrievedMetadata is present).

firstAuthorFamilyNameMatch

boolean

Output only. Whether the first author's family name matched between extracted and retrieved metadata.

searchRationale

string

Output only. Explanation from the Google Search grounding verification step (when run).

groundingUrls[]

object (GroundingUrl)

Output only. Web sources surfaced during Google Search grounding.

Verdict

Verification verdict for scholarly lookup and overall reference check.

Enums
VERDICT_UNSPECIFIED Default unspecified verdict.
OK Reference metadata matches scholarly database record.
MINOR_MISMATCH Minor discrepancy (e.g., publication year off by 1 or venue variation).
MAJOR_MISMATCH Major discrepancy in authors, year, or venue.
NOT_FOUND Reference not found in scholarly databases and unverified by search.
HALLUCINATED Reference flagged as likely hallucinated by Google Search grounding.
SKIPPED Non-paper entry (e.g., software package or URL) skipped during lookup.

SearchVerdict

Verdict from Google Search grounding verification.

Enums
SEARCH_VERDICT_UNSPECIFIED Default unspecified search verdict (search grounding not run).
NOT_HALLUCINATED Google Search grounding confirmed the work exists.
SEARCH_ERROR Google Search grounding encountered an execution or parsing error.

CitationMetadata

Structured bibliographic metadata for an extracted or retrieved work.

JSON representation
{
  "title": string,
  "authors": [
    {
      object (Author)
    }
  ],
  "publicationDate": {
    object (Date)
  },
  "journal": string,
  "volume": string,
  "pages": string,
  "doi": string,
  "urls": [
    string
  ],
  "source": string
}
Fields
title

string

Output only. Work title.

authors[]

object (Author)

Output only. Ordered list of authors.

publicationDate

object (Date)

Output only. Publication date (month and day left as 0 if just year).

journal

string

Output only. Journal, conference, or venue name.

volume

string

Output only. Volume identifier.

pages

string

Output only. Page range or article number.

doi

string

Output only. Digital Object Identifier (DOI).

urls[]

string

Output only. URLs associated with the reference.

source

string

Output only. Source database for retrieved metadata (e.g., "openalex", "crossref"). Empty on extractedMetadata.

Author

Author name components.

JSON representation
{
  "givenName": string,
  "familyName": string
}
Fields
givenName

string

Output only. Author given name / initials.

familyName

string

Output only. Author family name / surname (or organization name).

Date

Represents a whole or partial calendar date, such as a birthday. The time of day and time zone are either specified elsewhere or are insignificant. The date is relative to the Gregorian Calendar. This can represent one of the following:

  • A full date, with non-zero year, month, and day values.
  • A month and day, with a zero year (for example, an anniversary).
  • A year on its own, with a zero month and a zero day.
  • A year and month, with a zero day (for example, a credit card expiration date).

Related types:

JSON representation
{
  "year": integer,
  "month": integer,
  "day": integer
}
Fields
year

integer

Year of the date. Must be from 1 to 9999, or 0 to specify a date without a year.

month

integer

Month of a year. Must be from 1 to 12, or 0 to specify a year without a month and day.

day

integer

Day of a month. Must be from 1 to 31 and valid for the year and month, or 0 to specify a year by itself or a year and month where the day isn't significant.

FieldComparison

Per-field comparison result between extracted and retrieved metadata.

JSON representation
{
  "fieldKey": string,
  "match": boolean,
  "detail": string
}
Fields
fieldKey

string

Output only. Field key ("title", "authors", "year", "journal", "volume", "pages", "doi").

match

boolean

Output only. Whether the extracted and retrieved values matched.

detail

string

Output only. Human-readable comparison detail (e.g., "extracted=2023, found=2024 (diff=1)").

GroundingUrl

Web source URL surfaced during Google Search grounding verification.

JSON representation
{
  "title": string,
  "url": string
}
Fields
title

string

Output only. Source page title or domain.

url

string

Output only. Source URL.

DeepReviewRunConfig

Configuration options for the multi-agent document review execution pipeline.

JSON representation
{
  "topology": enum (Topology),
  "model": string,
  "geminiApiKey": string,
  "userPrompt": string,
  "geminiApiKeySet": boolean
}
Fields
topology

enum (Topology)

Optional. Review execution topology profile to use.

model

string

Optional. The Gemini model identifier to use for the review. If omitted, the server uses its default model. Unsupported values return INVALID_ARGUMENT.

geminiApiKey

string

Optional. Input only. Developer Bring-Your-Own-Key Gemini API key. When provided, requests are billed to the caller's Gemini API project. Input only; forwarded to the asynchronous review runner in the task payload and never persisted in database records or returned in review resources (see companion field geminiApiKeySet, AIP-147).

userPrompt

string

Optional. User-provided guidance, focus areas, or custom evaluation instructions passed to the review agents.

geminiApiKeySet

boolean

Output only. Indicates whether a developer Bring-Your-Own-Key Gemini API key was provided for this review run.

Topology

Execution topology quality profile for the review pipeline.

Enums
TOPOLOGY_UNSPECIFIED Default unspecified topology. The server uses its default topology (MID).
EXTRA_HIGH Extra high quality topology with exhaustive evaluation passes.
HIGH Standard high quality conference review topology.
MID Medium quality topology balancing review latency and depth.
LOW Low latency / fast turnaround topology.

Methods

create

Creates and initiates an asynchronous multi-agent review for a document.

get

Retrieves a specific review execution result.

list

Lists all review execution runs for a document.