1. Get a Kivo API key
Use a project-scoped API key for your Kivo organization. Store the one-time secret only in server-side configuration. Sensitive production traces should use Enterprise Worker Deployment instead of the hosted API.
Environment
export KIVO_API_BASE_URL="https://api.trykivo.co"
export KIVO_API_KEY="kivo_live_your_key"2. Prepare a review-run payload
A review run needs the AI output, supplied sources, intended use, and optional metadata. Kivo only performs claim-level source-support verification against the sources you provide.
review-run.json
{
"ai_output": "Customers can request refunds for any order within 60 days, including international orders.",
"sources": [
{
"title": "Refund policy",
"citation_label": "source 1",
"media_type": "text/plain",
"content": "Customers may request a refund within 30 days of purchase. International return shipping fees are not refunded."
}
],
"intended_use": "customer_facing",
"strictness": "standard",
"metadata": {
"workflow": "support_answer",
"environment": "quickstart"
}
}3. Submit the review run
curl
curl -sS "$KIVO_API_BASE_URL/v1/review-runs" \
-H "Authorization: Bearer $KIVO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"ai_output": "Customers can request refunds for any order within 60 days, including international orders.",
"sources": [
{
"title": "Refund policy",
"citation_label": "source 1",
"media_type": "text/plain",
"content": "Customers may request a refund within 30 days of purchase. International return shipping fees are not refunded."
}
],
"intended_use": "customer_facing",
"strictness": "standard",
"metadata": {
"workflow": "support_answer",
"environment": "quickstart"
}
}'Production create calls return `202` with a queued run and polling URL. The returned `request_id` is useful for logs and support.
202 response
{
"review_run": {
"id": "run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f",
"project_id": "9fd60878-b3a3-45ff-9ccf-7504c47a2c21",
"status": "queued",
"intended_use": "customer_facing",
"strictness": "standard",
"source_count": 1,
"claim_count": 0,
"unsupported_claim_count": 0,
"safe_use_status": null,
"gate_verdict": null,
"created_at": "2026-04-27T16:20:18.000Z",
"completed_at": null,
"capture_method": "api",
"question": null,
"metadata": {
"workflow": "support_answer",
"environment": "quickstart"
}
},
"queued": {
"review_run_id": "run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f",
"status": "queued",
"polling_url": "https://api.trykivo.co/v1/review-runs/run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f",
"recommended_poll_interval_seconds": 2
},
"polling_url": "https://api.trykivo.co/v1/review-runs/run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f",
"request_id": "req_01hw87ffx88w7m4a4qn1v2z7g0"
}4. Poll until completed
Poll status
curl -sS "$KIVO_API_BASE_URL/v1/review-runs/$REVIEW_RUN_ID" \
-H "Authorization: Bearer $KIVO_API_KEY"Poll every two seconds unless the response says otherwise. Stop polling when the status is `completed`, `failed`, or `cancelled`.
5. Fetch claims, verification, and the claim report
Claims
curl -sS "$KIVO_API_BASE_URL/v1/review-runs/$REVIEW_RUN_ID/claims" \
-H "Authorization: Bearer $KIVO_API_KEY"Verification results
curl -sS "$KIVO_API_BASE_URL/v1/review-runs/$REVIEW_RUN_ID/verification-results" \
-H "Authorization: Bearer $KIVO_API_KEY"Claim report
curl -sS "$KIVO_API_BASE_URL/v1/review-runs/$REVIEW_RUN_ID/claim-report" \
-H "Authorization: Bearer $KIVO_API_KEY"Claim report response
{
"id": "run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f_claim_report",
"review_run_id": "run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f",
"safe_use_status": "needs_repair",
"title": "Claim report",
"summary": "This review found 1 unsupported claim(s) and 0 citation issue(s) in the captured output.",
"unsupported_claims": [
{
"claim_id": "run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f_claim_1",
"claim_text": "Customers can request refunds for any order within 60 days",
"support_status": "unsupported",
"output_start_offset": 0,
"output_end_offset": 60,
"source_span_id": null,
"source_quote": null,
"reviewer_follow_up": "Should the output remove or revise claim `run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f_claim_1`?"
}
],
"citation_issues": [],
"evidence_notes": [],
"follow_ups": [
{
"claim_id": "run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f_claim_1",
"question": "Should the output remove or revise claim `run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f_claim_1`?"
},
{
"claim_id": null,
"question": "Is the intended use still correct for this output?"
}
],
"markdown": "# Claim report\n\nUse status: Needs Repair\nUnsupported claims: 1\nCitation issues: 0\nSource coverage: 0/1 claims\n\n## Summary\nThis review found 1 unsupported claim(s) and 0 citation issue(s) in the captured output.\n\n## Unsupported claims\n- Claim `run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f_claim_1`: The supplied sources do not support this claim: \"Customers can request refunds for any order within 60 days\"\n\n## Citation issues\n- No citation issues were found in the structured verification results.\n\n## Evidence notes\n- No partially supported claims were found in the structured verification results.\n\n## Follow-up questions\n- Should the output remove or revise claim `run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f_claim_1`?\n- Is the intended use still correct for this output?\n",
"compiler_version": "claim-report.2026-04-27.v1",
"policy_version": "claim-report-policy.2026-04-27.v1",
"metadata": {
"source_coverage": {
"claims_with_primary_source": 0,
"total_claims": 1
},
"leakage_check": {
"passed": true,
"errors": []
}
},
"created_at": "2026-04-27T16:20:24.000Z",
"updated_at": "2026-04-27T16:20:24.000Z",
"request_id": "req_01hw87mffegj48zyr7fzd71r82"
}Troubleshooting
Missing API key
{
"error": {
"code": "missing_api_key",
"message": "API key is required."
},
"request_id": "req_01hw87p6jkh5ezf9zr9de6d3a9"
}Usage limit
{
"error": {
"code": "usage_limit_exceeded",
"message": "Monthly review-run usage limit exceeded.",
"details": {
"requested_quantity": 1
}
},
"request_id": "req_01hw87wq6syf9mkqqxv4sdy9bf"
}