Lifecycle
| Status | Meaning | Caller action |
|---|---|---|
queued | The run was accepted and is waiting for processing. | Poll the run URL. |
processing | Extraction, verification, or claim report compilation is in progress. | Continue polling. |
completed | Review artifacts are available. | Fetch claims, verification results, or claim report. |
failed | Processing failed without producing complete review artifacts. | Inspect error fields and request ID before retrying. |
cancelled | The run is no longer being processed. | Do not use this run for workflow decisions. |
Create and poll
Create 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"
}Completed status
{
"id": "run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f",
"project_id": "9fd60878-b3a3-45ff-9ccf-7504c47a2c21",
"status": "completed",
"intended_use": "customer_facing",
"strictness": "standard",
"source_count": 1,
"claim_count": 1,
"unsupported_claim_count": 1,
"safe_use_status": "needs_repair",
"gate_verdict": {
"id": "run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f_gate_verdict",
"review_run_id": "run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f",
"verdict": "needs_repair",
"safe_use_status": "needs_repair",
"reasons": [
{
"code": "unsupported",
"message": "One or more claims are not supported by the supplied sources.",
"claim_id": "run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f_claim_1"
}
],
"strictness": "standard",
"mode": "advisory",
"metadata": {
"intended_use": "customer_facing",
"policy_version": "gate-policy.2026-04-27.v1"
},
"created_at": "2026-04-27T16:20:24.000Z"
},
"created_at": "2026-04-27T16:20:18.000Z",
"completed_at": "2026-04-27T16:20:24.000Z",
"capture_method": "api",
"question": null,
"metadata": {
"workflow": "support_answer",
"environment": "quickstart"
},
"error_code": null,
"error_message": null,
"ai_output": "Customers can request refunds for any order within 60 days, including international orders.",
"sources": [
{
"id": "run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f_source_1",
"title": "Refund policy",
"uri": null,
"citation_label": "source 1",
"media_type": "text/plain",
"content_sha256": "9f37b0f8e5f4b8a0a7c8948ecdf7d927650f5b5a46c44dd1de44f771d5df3a41"
}
],
"source_spans": [
{
"id": "run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f_span_1",
"source_document_id": "run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f_source_1",
"quote": "Customers may request a refund within 30 days of purchase.",
"start_offset": 0,
"end_offset": 59,
"metadata": {
"source_title": "Refund policy",
"citation_label": "source 1"
},
"created_at": "2026-04-27T16:20:24.000Z"
}
],
"verification_results": [
{
"id": "run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f_verification_1",
"atomic_claim_id": "run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f_claim_1",
"support_status": "unsupported",
"primary_source_span": null,
"verifier_name": "bravo-deterministic-source-verifier",
"verifier_version": "source-verification.2026-04-27.v1",
"verifier_provider": "deterministic",
"verifier_model": "source-verification-rules-v1",
"confidence": 0.74,
"rationale": "The supplied source states a 30-day refund window, not 60 days.",
"metadata": {
"citation_issue": "no_citation_required",
"candidate_count": 1
},
"created_at": "2026-04-27T16:20:24.000Z"
}
],
"claim_report": {
"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
}
},
"created_at": "2026-04-27T16:20:24.000Z",
"updated_at": "2026-04-27T16:20:24.000Z"
},
"request_id": "req_01hw87j6q7a27ez6p4dk4g0nsn"
}Artifacts
| Endpoint | Returns |
|---|---|
/v1/review-runs/{reviewRunId} | Status, counts, gate verdict, source-bounded use status, and error fields. Hosted API runs include original output and report artifacts; Enterprise Worker runs return metadata and storage pointers. |
/v1/review-runs/{reviewRunId}/claims | Atomic claims with support status and primary source span. |
/v1/review-runs/{reviewRunId}/verification-results | Verifier metadata, support status, confidence, rationale, and source spans. |
/v1/review-runs/{reviewRunId}/claim-report | Claim report JSON with unsupported claims, citation issues, evidence notes, and follow-ups. |
/v1/review-runs/{reviewRunId}/claim-report?format=markdown | Raw text/markdown claim report. The request ID is returned in the x-request-id header, not in a JSON envelope. |
For Enterprise Worker runs, detailed claim report contents stay in your storage. Kivo returns metadata, counts, verdicts, hashes, redacted categories, and optional opaque storage pointers.
Claims response
{
"items": [
{
"id": "run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f_claim_1",
"claim_type": "permission",
"text": "Customers can request refunds for any order within 60 days",
"normalized_text": "customers can request refunds for any order within 60 days",
"output_start_offset": 0,
"output_end_offset": 60,
"importance": 4,
"support_status": "unsupported",
"primary_source_span": null,
"verification_result": {
"id": "run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f_verification_1",
"atomic_claim_id": "run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f_claim_1",
"support_status": "unsupported",
"primary_source_span": null,
"verifier_name": "bravo-deterministic-source-verifier",
"verifier_version": "source-verification.2026-04-27.v1",
"verifier_provider": "deterministic",
"verifier_model": "source-verification-rules-v1",
"confidence": 0.74,
"rationale": "The supplied source states a 30-day refund window, not 60 days.",
"metadata": {
"citation_issue": "no_citation_required",
"candidate_count": 1
},
"created_at": "2026-04-27T16:20:24.000Z"
},
"extraction_provider": "deterministic",
"extraction_model": "bravo-rules-v1",
"extraction_prompt_version": "claim-extraction.2026-04-26.v1",
"extraction_confidence": 0.88,
"metadata": {
"citations": []
},
"created_at": "2026-04-27T16:20:24.000Z"
}
],
"request_id": "req_01hw87k7ksmx3q6wfz9pmy9m2d"
}Verification results response
{
"items": [
{
"id": "run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f_verification_1",
"atomic_claim_id": "run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f_claim_1",
"support_status": "unsupported",
"primary_source_span": null,
"verifier_name": "bravo-deterministic-source-verifier",
"verifier_version": "source-verification.2026-04-27.v1",
"verifier_provider": "deterministic",
"verifier_model": "source-verification-rules-v1",
"confidence": 0.74,
"rationale": "The supplied source states a 30-day refund window, not 60 days.",
"metadata": {
"citation_issue": "no_citation_required",
"candidate_count": 1
},
"created_at": "2026-04-27T16:20:24.000Z"
}
],
"request_id": "req_01hw87m7fbrq1rf90s29hpx18t"
}Claim report JSON
{
"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"
}Claim report markdown body
# Claim report
Use status: Needs Repair
Unsupported claims: 1
Citation issues: 0
Source coverage: 0/1 claims
## Summary
This review found 1 unsupported claim(s) and 0 citation issue(s) in the captured output.
## Unsupported claims
- 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"
## Citation issues
- No citation issues were found in the structured verification results.
## Evidence notes
- No partially supported claims were found in the structured verification results.
## Follow-up questions
- Should the output remove or revise claim `run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f_claim_1`?
- Is the intended use still correct for this output?