---
title: "Generate a cited diligence report"
method: POST
path: "/v1/diligence"
tags: ["Reports"]
---

# Generate a cited diligence report

`POST /v1/diligence`

## Request

- Base URL: `https://api.farofinance.app`
- URL: `https://api.farofinance.app/v1/diligence`
- Auth: HTTP bearer

Batch-verify up to 10 artifacts in parallel, then assemble a cited narrative from the observed signals. Every claim in the narrative must trace to a signal id; ungrounded claims are stripped. The LLM narrates evidence only — it never sets a verdict.

## Request body

- DiligenceIn: Body for `POST /v1/diligence` — batch verify + cited narrative report.
  - `artifacts` DiligenceArtifactIn[], required: Artifacts to verify in parallel (max 10).
    - `type` 'url' | 'payee' | 'message' | 'document', required
    - `value` string, required: Artifact value to check.

## Response `200`

Successful Response

- DiligenceReportOut: Rendered diligence report with cited evidence.
  - `request_id` string, required
  - `narrative` string, required: Markdown narrative; every claim cites signal ids.
  - `grounded` boolean, required: True when all narrative claims passed the groundedness gate.
  - `verdicts` VerdictResult[], required
    - `verdict` 'green' | 'yellow' | 'red', required
    - `confidence` number, required: Calibrated confidence in the verdict (honest about data completeness).
    - `artifact` Artifact, required
      - `type` 'url' | 'payee' | 'message' | 'document', required
      - `value` string, required: The normalized artifact string that was checked.
    - `reason` string, required: One plain-language line explaining the verdict — always present.
    - `recommended_action` 'allow' | 'warn' | 'block' | 'review', required
    - `signals` Signal[]: Evidence behind the verdict — deterministic checks, enrichment, reputation.
      - `name` string, required: Machine-readable signal id, e.g. `domain_age_days`.
      - `severity` 'info' | 'low' | 'medium' | 'high' | 'critical', required
      - `detail` string, required: Human-readable explanation of what was found.
      - `source` string, required: Integration that produced the signal, e.g. `safe_browsing`.
    - `explanation` string, nullable: Optional longer context (e.g. session repeat-check notes).
    - `request_id` string, required: Unique id for this request (also in the `X-Request-ID` response header).
    - `cached` boolean: True when served from the verdict cache (`X-Faro-Cache: hit`).
    - `first_seen` string, date-time, nullable: When Faro first saw this normalized node in the reputation graph.
    - `checked_at` string, date-time, nullable: When this verdict was computed.
  - `signals` object[], required: Flat catalog of citable signals referenced in the narrative.
  - `ungrounded_claims` string[]: Claims stripped by the groundedness gate (empty when grounded).

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/farofinance/apis/faro.md) · [All operations](https://skmtc.dev/farofinance/apis/faro/llms.txt) · [OpenAPI document](https://skmtc.dev/farofinance/apis/faro/revisions/205cdf54420b?raw)