API reference

Base URL and authentication

Use the API base URL configured for your Kivo workspace. Hosted API integrations send a scoped API key as `Authorization: Bearer kivo_...`. Enterprise Worker event calls use the run-scoped worker credential returned by `POST /v1/private-worker/review-runs`.

Base setup

export KIVO_API_BASE_URL="https://api.trykivo.co"
export KIVO_API_KEY="kivo_live_your_key"

Launched endpoints

POST/v1/review-runsreview_runs:create

Create a queued review run from one AI output and the supplied sources it should be checked against.

GET/v1/review-runs/{reviewRunId}review_runs:read

Read review-run status, counts, original output, and completion metadata.

GET/v1/review-runs/{reviewRunId}/claimsreview_runs:read

List extracted atomic claims with support status and primary source span.

GET/v1/review-runs/{reviewRunId}/verification-resultsreview_runs:read

List verifier outputs for each atomic claim.

GET/v1/review-runs/{reviewRunId}/claim-reportreview_runs:read

Fetch the claim report as JSON or markdown.

POST/v1/importsimports:create

Create review runs from structured JSON, JSONL, or CSV-like rows.

GET/v1/review-runsreview_runs:read

List review runs visible to the authenticated organization and project scope.

POST/v1/private-worker/review-runsprivate_worker_runs:create

Create a metadata-only Enterprise Worker run and receive a one-run worker credential.

POST/v1/private-worker/review-runs/{reviewRunId}/eventsworker credential

Accept metadata-only worker status, completion, or failure events.

POST/v1/private-worker/review-runs/{reviewRunId}/credential/rotateprivate_worker_runs:create

Rotate the run-scoped worker credential.

POST/v1/private-worker/review-runs/{reviewRunId}/credential/revokeprivate_worker_runs:create

Revoke the active run-scoped worker credential.

Deployment-specific API use

Mode	Endpoint family	What crosses into Kivo
`Kivo API Deployment`	/v1/review-runs and /v1/imports	Approved hosted packets, supplied sources, derived claims, source spans, claim reports, verdicts, and metadata.
`Enterprise Worker Deployment`	/v1/private-worker/review-runs	Run metadata, verdicts, counts, hashes, worker version, redacted categories, and opaque storage pointers only.
`Enterprise Worker eventing`	/v1/private-worker/review-runs/{id}/events	Metadata-only status, completion, or failure events authorized by a one-run worker credential.
`Credential lifecycle`	/credential/rotate and /credential/revoke	Replacement or revocation of the run-scoped worker credential.

Hosted API flow

Step	Endpoint	Result
`Submit one output`	POST /v1/review-runs	A queued review-run ID and polling URL.
`Poll completion`	GET /v1/review-runs/{reviewRunId}	Status, counts, gate verdict, and source-bounded use status.
`Fetch claims`	GET /v1/review-runs/{reviewRunId}/claims	Extracted atomic claims with support status.
`Fetch verification`	GET /v1/review-runs/{reviewRunId}/verification-results	Verifier metadata and source-support results.
`Fetch claim report`	GET /v1/review-runs/{reviewRunId}/claim-report	Reviewer-facing claim report as JSON or markdown.

Create review run

Property	Required	Notes
`ai_output`	yes	The model output to review. Maximum length is enforced by the API schema.
`sources`	yes	One to fifty supplied source documents.
`intended_use`	yes	internal_draft, customer_facing, regulated_workflow, action_taking, or eval_only.
`strictness`	no	advisory, standard, or strict. Defaults to standard.
`metadata`	no	Workflow metadata for traceability. Do not include secrets.

202 queued 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"
}

Read results

GET /v1/review-runs/{reviewRunId}

{
  "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"
}

GET /v1/review-runs/{reviewRunId}/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
    },
    "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"
}

GET /v1/review-runs/{reviewRunId}/claims

{
  "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"
}

GET /v1/review-runs/{reviewRunId}/verification-results

{
  "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"
}

Structured imports

Use `POST /v1/imports` for JSON, JSONL, or CSV-like rows that already contain an AI output and supplied sources. Each accepted row becomes a review run.

Import request

curl -sS "$KIVO_API_BASE_URL/v1/imports" \
  -H "Authorization: Bearer $KIVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rows":[{"external_id":"answer_001","ai_output":"Refunds are available for 60 days.","sources":[{"title":"Refund policy","content":"Customers may request a refund within 30 days of purchase."}],"intended_use":"customer_facing"}]}'

Account endpoints

These endpoints support usage and billing workflows around the review-run API.

Method	Endpoint	Scope	Use
`GET`	/v1/usage	billing:read	Read current plan usage, monthly limit, remaining review runs, and period dates.
`POST`	/v1/billing/checkout	billing:write	Create a Stripe Checkout session for a paid plan.
`POST`	/v1/billing/portal	billing:write	Create a Stripe Customer Portal session for an existing customer.

Errors

Error responses include a stable machine code, human-readable message, and `request_id`. Preserve that ID in your logs.

401

{
  "error": {
    "code": "missing_api_key",
    "message": "API key is required."
  },
  "request_id": "req_01hw87p6jkh5ezf9zr9de6d3a9"
}

429

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after the rate-limit window resets."
  },
  "request_id": "req_01hw88g5be6829q4wcx4pjft7n"
}

REST API for hosted review runs and worker metadata.