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

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.

## 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 `configuration` object accepts:

| Field          | Description                                                                                                                                                |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tier`         | `fast` for a quick initial screen or `agentic` for a more comprehensive review. The default is `agentic`.                                                  |
| `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.

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