Build with KKOS

One conversation in — a structured, correctable, reproducible model of a person out. Eleven trait dimensions, a confidence value and the evidence behind every score.

Introduction

KKOS is the modelling engine behind KKmatch. It turns a short spoken or typed conversation into a behavioural profile — not a personality quiz result, and not free-form text. Three properties shape every endpoint:

• Structured. The output is a fixed schema: eleven trait dimensions, each with a score (0–100), a confidence (0–1) and the evidence it was derived from.
• Correctable. The person can overturn any trait through trait feedback. Corrections are stored as strong labels next to the model's own weak labels — that pair is the training signal.
• Reproducible. The transcript is stored with the model, so /mirror/model/{model_id}/regenerate rebuilds it from the same input and versions[] keeps every earlier snapshot.

The eleven dimensions:

All endpoints are RESTful and return JSON. Current model generation: hm-v1. Status: v1 stable

Base URL

https://kkmatch.com/api/v1

Everything is served over HTTPS. There is no separate sandbox host — use the free plan for integration testing.

Authentication

There are two kinds of credential, and they are not interchangeable:

Every non-public /api/* path requires one of the two credentials. A request with neither gets:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: ApiKey realm="KK Match API"

{
  "detail": "Missing or invalid API key",
  "hint": "Registered users: get a free API key at /kkos-ai.html (API Access). Then send it as X-API-Key.",
  "docs": "https://kkmatch.com/docs"
}

Quick start

Three calls take you from an empty session to a finished model. Replace $TOKEN with a session token from /auth/login-code.

# 1 — open a session (the assistant greets first)
curl -X POST https://kkmatch.com/api/v1/mirror/start \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode":"text","consent":{"analysis_consent":true,"storage_consent":true}}'

# 2 — send the person's replies, one call per turn
curl -X POST https://kkmatch.com/api/v1/mirror/message \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<sid>","message":"I usually decide fast, then adjust."}'

# 3 — close the session and build the model
curl -X POST https://kkmatch.com/api/v1/mirror/complete \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<sid>","transcript":[{"role":"user","content":"..."}]}'

A healthy /complete response carries the whole model object plus the canonical redirect the product uses:

{
  "session_id": "b6f2...",
  "model_id": "8c1a...",
  "redirect": "/mirror-result.html?model=8c1a...",
  "model": {
    "model_id": "8c1a...",
    "model_version": "hm-v1",
    "version": 1,
    "overall_confidence": 0.6,
    "traits": [
      { "name": "directness", "score": 78, "confidence": 0.7,
        "evidence": ["I usually decide fast, then adjust."],
        "uncertainty": [], "alternative_explanations": [] }
    ],
    "summary": "...",
    "communication_manual": "...",
    "recommended_next_questions": ["..."]
  }
}

If the modelling LLM cannot be parsed, the endpoint retries with a compact prompt before falling back — the response still contains all eleven traits so your client never has to handle a missing field.

Endpoint overview

Everything under /api/v1. session token marks endpoints that need a signed-in user.

Start a session

Request body

Response (200)

{
  "session_id": "b6f2c1d0-...",
  "mode": "text",
  "ai_state": "greeting",
  "reply": "Hi, I'm Human Mirror. I'm not here to test you — just to talk. ..."
}

Send a message

Request body

Response (200)

{
  "session_id": "b6f2c1d0-...",
  "reply": "That's a distinctive way to describe it — ...",
  "state": "engaged",
  "events": ["question_answered", "emotional_shift"]
}

events are real-time interaction signals detected in the utterance itself (for example question_answered, emotional_shift). They are accumulated on the session and travel into the training sample for that session.

Build the model

Request body

When video signals are present they are blended with the spoken content, with the strongest influence on emotional_expression, engagement and uncertainty_response.

Each trait object in the response can also carry uncertainty and alternative_explanations (at most one entry each) — the model states where it is unsure instead of hiding it. A compliance guard removes any language that would diagnose a medical or mental condition or infer a protected attribute.

Retrieve a model

Correct a trait

Request body

The correction is written both to the feedback log and onto the trait, so the next regeneration can take it into account, and it is included in that session's training sample as a strong label.

Message protocol

Two protocols exist because the product has two conversational paths. Pick by latency need, not by feature set — both end in the same model.

Path A — turn-based REST

Simplest to integrate, works from any language, and is what the three-call quick start uses. You control turn boundaries:

Path B — realtime WebSocket

Both paths accumulate into the same transcript, so a session that started in realtime voice can be completed through the REST endpoint and produces one model with one version history.

Voices & TTS

{
  "kkos_enabled": true,
  "chattts_enabled": false,
  "default_provider": "kkos",
  "default_kkos_voice": "Colton Rivers",
  "kkos":  [ { "id": "...", "name": "Colton Rivers" } ],
  "edge":  [ { "id": "en-US-AriaNeural", "name": "Aria (US Female)" }, "..." ],
  "chattts_styles": [ "warm_narrator", "professional", "casual", "..." ]
}

Health probes: GET /mirror/tts/health and GET /mirror/evi/health?probe=1. Both report reachability and configuration state without ever returning a credential.

Speech-to-text

Response: {"text": "..."}. Audio shorter than 800 bytes returns {"text":"", "reason":"too_short"} rather than an error, so you can stream aggressively and discard the empty results.

Share & Challenge

curl -X POST https://kkmatch.com/api/v1/challenge/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<sid>","model_id":"<model_id>"}'

Then GET /challenge/{challenge_id} to read it and POST /challenge/{challenge_id}/accept when the invited person finishes their own session. Once both sides exist, POST /mirror/compare produces the dyadic view of the two models.

Account & usage

{
  "ok": true,
  "user":   { "user_id": "...", "email": "...", "is_admin": false },
  "stats":  { "models_count": 3, "deep_unlocked_count": 1,
              "challenges_count": 2, "matches_count": 1,
              "api_keys_count": 1 },
  "models": [ { "model_id": "...", "version": 2, "overall_confidence": 0.6,
                "deep_unlocked": true, "shared": false } ],
  "challenges": [ ... ],
  "matches": [ ... ],
  "subscription": { "tier": "pro", "status": "active" }
}

Plans & billing

{
  "currency": "USD",
  "plans": [
    { "id": "free", "name": "Free", "category": "individual",
      "price_monthly_usd": 0,   "price_yearly_usd": 0,
      "conversations_included": 30,  "overage_price_usd": null,
      "seats": 1, "highlight": false, "features": ["..."] }
  ]
}

Paid plans are billed in USD through PayPal, monthly or yearly. Per-conversation economics — what a plan includes and what a conversation actually costs to serve — are laid out on the pricing page.

Get an API key

Keys are self-served, not email-gated. Sign in, open your account page, and issue one:

Quotas & limits

Limits are enforced where they are listed. Values below are the current production ones.

Request limits

Consent keys

/mirror/start accepts six explicit consent flags: two are required, two depend on the input mode you choose, and two are optional.

See Trust & Privacy for what each choice does to the stored data.

Plan quotas

Conversation volume is a billing quota rather than a rate limit. Current monthly allowances are 30 (Free), 300 (Plus), 1,000 (Pro), 2,000 (Team, shared across 5 seats) and 10,000 (Business, shared across 20 seats). Overages are quoted per conversation on the pricing page. The live numbers always come from GET /plans.

Model providers

KKOS is a pipeline of three components. Knowing where each one runs tells you what is metered and what can fail:

The gateway is called with retry-on-429 backoff, up to four attempts. Reasoning models bill reasoning and content against the same token budget, which is why the modeller is given a generous output budget and instructed to keep evidence arrays short — a truncated JSON payload would otherwise fall back instead of returning a real model.

Metrics & evaluation

Numbers on our marketing pages are product illustrations, not live statistics. This section defines what we actually measure, so you can tell the difference.

What a model reports

How the model is validated

• Schema conformance. Every response must contain all eleven dimensions with numeric score and confidence. Violations are recorded on the stored model as schema_violations rather than silently dropped — you can audit how often a generation was repaired.
• Correction rate. The share of traits a person marks wrong through trait feedback is the primary quality signal, because it is the one number the model cannot write itself.
• Inter-version stability. Regenerating from the same transcript should not move scores wildly; large deltas between versions[] are treated as a regression, not as new insight.
• Strong < weak labels. Each session ships as one training sample with weak labels (model-produced traits) and, later, strong labels (user corrections). The pair is the training signal; samples live in a JSONL log with the turn timeline, prosody trace and video signal sequence attached.

Errors

Standard HTTP status codes, JSON bodies throughout. The detail string is stable enough to branch on.

Server status

Three probes tell you where a failure is:

There is no email-based status page yet. During an incident, degraded voice falls back to Edge TTS automatically when provider is left on auto — the modelling path itself has no fallback and will report an error instead of returning a fabricated model.

Changelog

Need help?

Email support@kkmatch.com for technical questions, quota increases or enterprise contracts. For sales and private deployments, use the contact form.