API Reference

The Veriva public REST API is the contract behind the CLI, GitHub Action, VS Code extension, and customer Webhook hooks. The webapp itself uses internal tRPC procedures and is not part of this surface.

Authentication

Every request must include a valid API key in the Authorization: Bearer header. Generate keys in Settings → API Keys; they are scoped per-org and inherit the role of the issuing user (OWNER, ADMIN, or MEMBER).

curl https://api.veriva.dev/v1/repos \
  -H "Authorization: Bearer $VERIVA_TOKEN"

Base URL

• Production: https://api.veriva.dev/v1
• Beta: https://api-beta.veriva.dev/v1

Resources

POST /analyze

Run the full 10-stage governance pipeline against a unified diff. Synchronous for diffs under 200kb; asynchronous (returns a pipelineRunId) above. Each call counts against the org's monthly PR budget.

curl -X POST https://api.veriva.dev/v1/analyze \
  -H "Authorization: Bearer $VERIVA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "diff": "diff --git a/src/auth.ts ...",
    "repoFullName": "neocharge/firmware",
    "headSha": "abc1234",
    "prTitle": "fix: reject expired tokens"
  }'

GET /runs/{runId}

Poll the status of an async pipeline run. Returns the same shape as the synchronous /analyze response once status: completed.

GET /pull-requests

Paginated list of analyzed pull requests for the org, optionally filtered by repoId. Use nextCursor for the next page.

GET /pull-requests/{prId}/findings

All findings emitted for a PR including the EXPLAIN provenance object per finding.

GET /agents · POST /agents

List or register AgentIdentity rows. The token returned on creation is shown once — store it in the agent's environment so subsequent PRs can attribute findings.

POST {your-url} (Webhook hook reference)

When you register a Webhook hook in Veriva, we POST a WebhookHookPayload to your URL during AI REVIEW. Respond within 5 seconds with a findings[] array. Requests are signed with HMAC-SHA256 in the X-Veriva-Signature header.

Errors

All non-2xx responses return JSON of shape { error: string, code?: string, details?: object }.

• 401 Unauthorized — missing/invalid API key
• 402 Quota Exceeded — plan PR/cost ceiling reached
• 404 Not Found — resource not visible to this key's org
• 429 Rate Limited — back off and retry; honor Retry-After header when present

Rate limits

Per-API-key hourly quotas scale with the org's plan: Hobby 100 req/hour, Pro 1,000 req/hour, Ultra 10,000 req/hour, Enterprise unlimited. Limits reset on a rolling hourly window per key. Responses past the quota return 429 with a Retry-After header (seconds) — honor it. Webhook deliveries from GitHub do not count against API rate limits.