Deep Review API

The Deep Review API is a REST interface for automated, in-depth document reviews. It lets developers and researchers programmatically ingest documents, run multi-stage reviews, inspect structured critiques, and manage document lifecycles.

Learn more at research.google/deepreview.

Key capabilities

  • Document management: Programmatically upload documents using media streaming, retrieve document metadata, and track review status.
  • Automated reviews: Trigger comprehensive multi-angle reviews and retrieve the synthesized review Markdown report and anchored critique comments.
  • Anchored feedback: Access structured comments anchored to specific spans or bounding box coordinates on PDF pages.
  • APIs Explorer integration: Explore and execute requests directly in your browser using the REST API reference.

Quick example

Before running the example, set your active Google Cloud project, enable the Deep Review API, and configure Application Default Credentials with the https://www.googleapis.com/auth/cloud-platform and https://www.googleapis.com/auth/drive.file scopes:

gcloud config set project YOUR_PROJECT_ID
gcloud services enable deepreview.googleapis.com
gcloud auth application-default login --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/drive.file

The following example demonstrates uploading a manuscript and initiating a review:

Python

import os
import requests

API = "https://deepreview.googleapis.com"
TOKEN = os.popen("gcloud auth application-default print-access-token").read().strip()
PROJECT_ID = os.popen("gcloud config get-value project").read().strip()

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "x-goog-user-project": PROJECT_ID,
}

# 1. Upload manuscript PDF
with open("manuscript.pdf", "rb") as f:
    doc_resp = requests.post(
        f"{API}/upload/v1/documents?uploadType=media",
        headers={**headers, "Content-Type": "application/pdf"},
        data=f.read(),
    )
if not doc_resp.ok:
    raise RuntimeError(
        f"Failed to upload document ({doc_resp.status_code}): {doc_resp.text}"
    )
doc = doc_resp.json()
print(f"Uploaded document: {doc['name']}")

# 2. Trigger automated multi-agent review
op_resp = requests.post(
    f"{API}/v1/{doc['name']}/reviews",
    headers={**headers, "Content-Type": "application/json"},
    json={"runConfig": {"topology": "MID"}},
)
if not op_resp.ok:
    raise RuntimeError(
        f"Failed to initiate review ({op_resp.status_code}): {op_resp.text}"
    )
op = op_resp.json()
print(f"Review initiated: {op['name']}")

REST

# 1. Upload manuscript
DOC=$(curl -sS -X POST "https://deepreview.googleapis.com/upload/v1/documents?uploadType=media" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: $(gcloud config get-value project)" \
  -H "Content-Type: application/pdf" \
  --data-binary "@manuscript.pdf")

DOC_NAME=$(echo "$DOC" | jq -r 'select(.name != null) | .name')
if [ -z "$DOC_NAME" ]; then
  echo "Failed to upload document: $DOC" >&2
else
  echo "Document created: $DOC_NAME"

  # 2. Initiate review
  OPERATION=$(curl -sS -X POST "https://deepreview.googleapis.com/v1/${DOC_NAME}/reviews" \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "x-goog-user-project: $(gcloud config get-value project)" \
    -H "Content-Type: application/json" \
    -d '{"runConfig": {"topology": "MID"}}')

  OP_NAME=$(echo "$OPERATION" | jq -r 'select(.name != null) | .name')
  if [ -z "$OP_NAME" ]; then
    echo "Failed to initiate review: $OPERATION" >&2
  else
    echo "Operation: $OP_NAME"
  fi
fi

Next steps