---
title: Using the Verify API | Developer Documentation
description: Upload a document, create a Verify job, retrieve its authenticity assessment, and inspect supporting evidence through the Preview REST 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](#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:

Terminal window

```
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:

Terminal window

```
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:

Terminal window

```
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:

Terminal window

```
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](./#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:

Terminal window

```
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.