Kivo

Imports

Batch structured AI outputs into review runs.

Imports are for teams with existing structured AI-output exports or support workflow batches. Use API capture for live workflow integration.

When to use imports

Use caseRecommended path
Live AI product workflowPOST /v1/review-runs
CSV or JSONL export from support toolingPOST /v1/imports
Offline verification batchPOST /v1/imports with the intended_use that matches the original workflow.
Manual debuggingUse a small structured JSON sample, not raw chat logs.

Row shape

Each row must include `ai_output` and at least one supplied source. Use `external_id` to map Kivo results back to your source system.

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

Create import

Request
curl -sS "$KIVO_API_BASE_URL/v1/imports" \
  -H "Authorization: Bearer $KIVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "media_type": "application/x-ndjson",
    "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"
      }
    ]
  }'
202 response
{
  "id": "import_01hw8894n1v3a9k5sx5v2t3q7b",
  "project_id": "9fd60878-b3a3-45ff-9ccf-7504c47a2c21",
  "status": "completed",
  "capture_method": "upload",
  "row_count": 2,
  "accepted_count": 2,
  "rejected_count": 0,
  "validation_errors": [],
  "created_at": "2026-04-27T16:22:00.000Z",
  "review_run_ids": [
    "run_7f4f21e2-3d40-48a3-85f0-9f97e5f61b2f",
    "run_3a7b2bf6-bd90-4da2-9b0e-22f807b6f83c"
  ],
  "request_id": "req_01hw889zps5gr7q8m7jqt2wzc2"
}

Import statuses

StatusMeaning
uploadedThe batch was accepted.
mapping_requiredField mapping needs attention before runs can be created.
queuedRows are queued for review processing.
processingRuns are being created or processed.
completedAccepted rows have review-run IDs.
failedThe import failed closed.
cancelledThe import is no longer being processed.