Agent API
API Reference
Detailed technical reference for the canonical POST /api/v2/audit endpoint.
POSThttps://tryverdict.xyz/api/v2/audit
Request Body
The request body must be a JSON object containing exactly one required field:
| Field | Type | Required | Description |
|---|---|---|---|
| url | string | Yes | The valid public HTTP/HTTPS URL of the company or software startup to investigate. |
Request Example
{
"url": "https://linear.app"
}Response Body (200 OK)
The endpoint returns a structured JSON payload summarizing the audit verdict and evidence coverage:
| Property | Type | Description |
|---|---|---|
| reportId | string | Permanent unique identifier for the persisted audit memo. |
| overallScore | number | Growth Readiness Score from 0 to 100. |
| company_name | string | Normalized company/product name identified from root evidence. |
| identity | object | Normalized identity profile (company_name, inferred_description, target_audience, primary_cta). |
| the_verdict | object | Executive synthesis (status, primary_constraint, highest_opportunity, estimated_impact). |
| score_interpretation | string | Qualitative narrative explaining the overall Growth Readiness Score. |
| priority_matrix | array | Ranked action items with task, why, impact, and effort ratings. |
| pillars | object | Qualitative evaluations per growth dimension (confidence, reason, strengths, weaknesses) without numeric score. |
| sources | array | Admitted evidence sources supporting the audit (url, path, role, category, keyFindings). |
| pagesInspected | number | Total number of pages successfully acquired/fetched during the investigation pass. |
| pagesAccepted | number | Total number of acquired pages admitted through the relevance boundary. |
| stopReason | string | Investigation completion reason (e.g. 'sufficient', 'page_budget', 'no_candidates'). |
| evidenceCoverage | object | Aggregate evidence coverage metrics (pagesTotal, pagesAcquired, pagesAccepted, charsTotal, categories). |
HTTP Status Codes
| Status | Code | Meaning |
|---|---|---|
| 200 | OK | Audit successfully completed and persisted. |
| 400 | INVALID_REQUEST | Invalid JSON request body or unexpected request shape. |
| 400 | INVALID_URL | Malformed URL, non-HTTP scheme, or forbidden IP address. |
| 402 | PAYMENT-REQUIRED | x402 payment challenge issued with Base USDC payment requirements. |
| 422 | AUDIT_UNAVAILABLE | Target site is unreachable, blocked, or not auditable. |
| 503 | AUDIT_TEMPORARILY_UNAVAILABLE | Transient model or upstream network capacity limitation. |
| 500 | AUDIT_FAILED | Unhandled internal error during audit execution. |
| 500 | X402_CONFIGURATION_ERROR | Server-side x402 payment rail misconfiguration. |