Using the Verify API

Preview

Verify is retired

Verify is no longer part of the published API surface, and these pages are kept for reference only. It was never available through an SDK — see SDK availability below. The endpoints under /api/alpha/verify/ remain live for existing integrations, but the product is unsupported and no longer documented.

The Verify API runs an asynchronous authenticity review for a document or image. API access is limited during the Preview and the API may change.

SDK availability

Verify was never generated into any LlamaCloud SDK. It was reachable only over REST, at /api/alpha/verify/, so there is no client method to pin a version of or migrate away from — code that calls Verify calls the HTTP endpoints directly, and is unaffected by any SDK upgrade. It left the published API surface on 2026-08-25.

Before you begin

To call the Verify API, you need:

• A LlamaCloud API key with access to Verify
• The ID of the LlamaCloud project that will own the job
• A PDF, DOCX, PNG, JPEG, or WebP file to review

Set the API key and project ID as environment variables:

export LLAMA_CLOUD_API_KEY="llx-..."
export PROJECT_ID="YOUR_PROJECT_ID"

Run a Verify job

1. Upload the file

Upload the document with the Files API:

curl --request POST \
  "https://api.cloud.llamaindex.ai/api/v1/beta/files?project_id=${PROJECT_ID}" \
  --header "Authorization: Bearer ${LLAMA_CLOUD_API_KEY}" \
  --form "file=@document.pdf" \
  --form "purpose=user_data"

Save the id from the response as FILE_ID.

2. Create the job

Create a Verify job for the uploaded file:

curl --request POST \
  "https://api.cloud.llamaindex.ai/api/alpha/verify?project_id=${PROJECT_ID}" \
  --header "Authorization: Bearer ${LLAMA_CLOUD_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{
    "file_input": "FILE_ID",
    "configuration": {
      "tier": "agentic"
    }
  }'

The response includes the Verify job id and its initial status. Save the id as JOB_ID.

The request body accepts:

Field	Description
file_input	Required. The ID of the uploaded file to review. Files are currently the only supported input, and the job’s document_input_type always reflects a file input.
configuration	Optional review configuration; defaults apply when omitted.
transaction_id	Optional idempotency key, scoped to the project. Reusing a key returns the original job; the new request body is ignored.
webhook_configurations	Optional list of outbound webhook endpoints to notify on job status changes.

The configuration object accepts:

Field	Description
tier	fast for a quick initial screen or agentic for a more comprehensive review. The default is agentic. The fast tier is designed for scans and born-digital documents; photographed documents, such as phone captures, should use the agentic tier for reliable results.
target_pages	Optional comma-separated, 1-based PDF page numbers or ranges, such as 1,3,5-7. Omit it to review every page. This field is ignored for other file types.

3. Retrieve the result

Verify jobs move through PENDING and RUNNING before reaching COMPLETED, FAILED, or CANCELLED. Request the result while checking the job status:

curl --request GET \
  "https://api.cloud.llamaindex.ai/api/alpha/verify/JOB_ID?project_id=${PROJECT_ID}&expand=result" \
  --header "Authorization: Bearer ${LLAMA_CLOUD_API_KEY}"

When the status is COMPLETED, the result object includes:

Field	Description
verdict	The overall authenticity assessment.
overall_score	The document’s doctoring likelihood from 0 to 1.
confidence	How strongly the available evidence supports the verdict, from 0 to 1.
tampering_score	Likelihood that a real document was edited locally, from 0 to 1.
synthetic_score	Likelihood that the document was fabricated as a whole, from 0 to 1.
reasoning	A plain-language explanation of the verdict.
composite_scores	Scores for the different authenticity questions that applied to the document.
suspect_regions	Ranked document areas that contributed to the assessment, when findings can be localized.

See Interpreting Verify findings for guidance on using these fields in a review workflow.

4. Inspect supporting evidence

After a job completes, retrieve the detailed findings behind the result:

curl --request GET \
  "https://api.cloud.llamaindex.ai/api/alpha/verify/JOB_ID/details?project_id=${PROJECT_ID}" \
  --header "Authorization: Bearer ${LLAMA_CLOUD_API_KEY}"

The details include supporting evidence, grouped scores, localized regions, visual overlays, and checks that could not run. A check listed as unavailable did not produce a clean result; it did not run successfully for that file.

Each localized region carries a review field with the reviewer’s verdict on that candidate: confirmed, dismissed, or unsure, or an empty string when the region was not individually reviewed. A review_note explains the verdict. Dismissed candidates are excluded from the curated suspect_regions list in the job result but remain visible here.

Heatmap URLs expire

Visual overlays are returned as presigned URLs that expire about an hour after the response is generated. Treat them as temporary download links: if you need overlays for an audit trail or later review, download the image bytes and store them yourself. Do not persist the URLs — a stored URL will stop working. Re-requesting the details endpoint issues fresh URLs for as long as the job is retained.

Manage Verify jobs

Action	Method and path
Create a job	POST /api/alpha/verify
Retrieve a job	GET /api/alpha/verify/{job_id}
Retrieve supporting evidence	GET /api/alpha/verify/{job_id}/details
List jobs	GET /api/alpha/verify
Cancel a running job	POST /api/alpha/verify/{job_id}/cancel

All requests require the project_id query parameter. List requests can be filtered by status, job ID, or creation time and use page_size and page_token for pagination.