Kivo

SDKs and examples

Use REST examples from trusted server-side code.

Use these TypeScript, Python, and JSONL examples to connect backend services, jobs, or worker runtimes to Kivo.

Client policy

Transparent clients

Keep review-run IDs, polling URLs, intended use, and source payloads visible in your integration code.

OpenAPI aligned

Generated clients should track the documented OpenAPI contract.

Server-side keys

Every example assumes a backend or trusted worker environment.

TypeScript

Node or Next.js server code
const response = await fetch(`${process.env.KIVO_API_BASE_URL}/v1/review-runs`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KIVO_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    ai_output: output,
    sources,
    intended_use: "customer_facing",
    strictness: "standard",
    metadata: {
      workflow: "support_answer"
    }
  })
});

if (!response.ok) {
  const error = await response.json();
  throw new Error(`Kivo request failed: ${error.error?.code} ${error.request_id}`);
}

const accepted = await response.json();
console.log(accepted.review_run.id, accepted.polling_url);

Python

requests
import os
import requests

response = requests.post(
    f"{os.environ['KIVO_API_BASE_URL']}/v1/review-runs",
    headers={
        "Authorization": f"Bearer {os.environ['KIVO_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "ai_output": output,
        "sources": sources,
        "intended_use": "customer_facing",
        "strictness": "standard",
        "metadata": {"workflow": "support_answer"},
    },
    timeout=30,
)
response.raise_for_status()
accepted = response.json()
print(accepted["review_run"]["id"], accepted["polling_url"])

Import fixture

Use JSONL fixtures for support exports, replay batches, and offline integration tests. Keep fixture sources copy-safe and free from secrets.

sample.jsonl
{"external_id":"answer_001","question":"What is the refund window?","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"}
{"external_id":"answer_002","question":"Can admins export logs?","ai_output":"Admins can export audit logs.","sources":[{"title":"Admin guide","content":"Admins can export audit logs from the security workspace."}],"intended_use":"internal_draft"}

Example coverage

TypeScript

Create review runs, poll status, fetch claims, and fetch claim reports.

Python

Support batch reviews, notebook audits, and backend processing pipelines.

HTTP fixtures

Use copy-safe request examples for manual tests and integration checks.