Reports

Submit first-party feedback when Faro got it wrong — or when you know an artifact is bad. Reports feed the reputation graph: the next check on that node re-evaluates instead of serving a stale green verdict.

Use this when:

• Faro returned 🟢 but you know the link, payee, or message is malicious
• Faro returned 🔴 or 🟡 but the artifact is legitimate (false_positive)

You can also submit feedback from the MCP Apps verdict card — the card's "Report wrong verdict" button calls the MCP tool report_verdict, which writes through the same submit_report path as POST /v1/reports below (reporter handle mcp_app, same cache invalidation and reputation graph). See /docs/mcp.

Diligence reports

POST /v1/diligence — batch-verify artifacts and get a cited narrative (markdown) assembled from the observed signals. Every claim must cite a signal id; ungrounded claims are stripped. The LLM narrates evidence only — it never sets a verdict.

curl -X POST https://api.farofinance.app/v1/diligence \\
  -H "Authorization: Bearer $FARO_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "artifacts": [
      { "type": "url", "value": "https://merchant.example" },
      { "type": "payee", "value": "vendor@okaxis" }
    ]
  }'

Response includes narrative, grounded, verdicts, signals (citable catalog), and any ungrounded_claims removed by the gate.

Entity watches (alerts)

Register interest in a counterparty after verify-before-pay so you receive artifact.flagged webhooks if it turns bad later — even if you have not checked it recently:

curl -X POST https://api.farofinance.app/v1/me/watch \\
  -H "Authorization: Bearer $FARO_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{ "type": "payee", "value": "merchant@okaxis" }'

List watches with GET /v1/me/watch; remove with DELETE /v1/me/watch (same body). Requires a self-serve API key (same as dashboard routes).

Submit a report

POST /v1/reports — Bearer auth, returns 202 Accepted.

curl -X POST https://api.farofinance.app/v1/reports \
-H "Authorization: Bearer $FARO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "type": "url",
  "value": "http://sbi-kyc-update.xyz/verify",
  "kind": "phishing"
}'

Request body

Report kinds

Response

{
  "accepted": true,
  "artifact_id": "domain:sbi-kyc.xyz",
  "message": "Report recorded. The next check on this artifact will re-evaluate."
}

artifact_id is the normalized reputation node (domain for URLs, lowercased payee handle, content hash for messages) — the same key the engine uses for caching and tier-2 lookup.

What happens under the hood

1. Stored — row in the reports table, tied to the normalized node.
2. Cache invalidated — any cached 🟢 or 🟡 verdict for that node is deleted immediately so the next verify call does not serve stale "safe."
3. Future checks — tier-2 reputation emits a reputation_reports signal; multiple reports or other high signals can shift the verdict on re-check.

Related