Using the Verify 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:

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

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.

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.