Human-AI Chat Interaction Observatory

Two URLs are usually enough

Three things that shape the whole integration

The flow

   your chat app                      Observatory
   ────────────                       ───────────
   user sends message  ──────────▶  POST /turns          → 201 + Layer 1
   assistant streams…
   assistant completes ──────────▶  POST /turns          → 201 + Layer 1
                                          │
                                          ├─ queued: speech acts
                                          └─ queued: LCC / ICCC
   SSE subscriber      ◀──────────  analysis.core.completed
                       ◀──────────  analysis.speech_act.completed
                       ◀──────────  iccc.updated

Two analysis layers, and they are separate on purpose. Layer 1 is deterministic and inline: token ratios, lexical measures, timing, speech-act structure, participation, trajectory. Layer 2 is optional, queued, and never enabled implicitly — two theoretically distinct engines (LCC and ICCC) over a shared semantic kernel. There is no merged score, and there is not going to be one.

Authenticate as an application

Your token needs both the application_client role and the owner's subject in an act.sub (RFC 8693) or on_behalf_of claim.

Authorization: Bearer <token>

A delegation claim without that role is rejected with 401 delegation_forbidden, so a leaked user token cannot be replayed as an application. The Observatory derives an internal owner key from the subject — you never send an owner id in a body, and it is never transmitted back to you.

Development (mock mode)

When a deployment runs AUTH_MODE=mock — which configuration refuses to start with in production — identity comes from headers. Useful before your OIDC provider is wired up.

X-Mock-Subject: demo-owner
X-Mock-Roles: application_client
X-Mock-On-Behalf-Of: end-user-42

Create the thread once per conversation

curl -X POST "http://hwaichatanalysis.skoonline.org/api/v1/threads" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "threadId": "conv_8f21",
    "title": "Support conversation",
    "interactionType": "general_dyad",
    "consentVersion": "your-consent-v3",
    "sourceApplicationId": "your-app",
    "participants": [
      {"participantId": "user", "type": "human", "roles": ["peer"]},
      {"participantId": "bot",  "type": "assistant", "roles": ["assistant"],
       "model": "claude-sonnet-5", "provider": "anthropic"}
    ]
  }'

Supplying your own threadId makes it idempotent — a retry returns the existing thread rather than creating a second one. Participants can also be added mid-conversation with POST /threads/:threadId/participants.

Identifiers are opaque: [A-Za-z0-9][A-Za-z0-9_-]{0,127}, with no personal information in them. A violation is a 400 unsafe_identifier, which is a validation rule rather than a suggestion.

Post each message as it completes

curl -X POST "http://hwaichatanalysis.skoonline.org/api/v1/threads/conv_8f21/turns" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{
    "turnId": "msg_8412",
    "participantId": "bot",
    "speakerType": "assistant",
    "text": "It uses a least recently used policy.",
    "submittedAt":  "2026-04-14T09:02:11.480Z",
    "firstTokenAt": "2026-04-14T09:02:12.140Z",
    "lastTokenAt":  "2026-04-14T09:02:14.980Z",
    "usage": {"visibleOutputTokens": 118, "totalApiInputTokens": 3120}
  }'

Request fields (* = required)

What each optional field buys you

The response

{
  "created": true,
  "contribution": { "turnId": "msg_8412", "sequence": 4, "…": "…" },
  "analysis": {
    "layer1": { "…": "per-turn measures, already computed" },
    "layer1Status": "completed",
    "layer2Status": "queued",
    "speechActStatus": "queued"
  },
  "jobIds": ["job_…"]
}

201 for a new turn, 200 for an idempotent replay. layer1 is there immediately; the two queued statuses resolve over SSE.

Backfill and buffer flushes

POST http://hwaichatanalysis.skoonline.org/api/v1/threads/conv_8f21/turns/batch
{ "turns": [ { "…": "same shape as a single turn" } ] }

1–500 turns, ingested sequentially so ordering and sequence assignment are preserved. Use it for backfill or to flush a retry buffer — not for the live path, where one-at-a-time keeps the latency measures honest.

Subscribe to results

GET http://hwaichatanalysis.skoonline.org/api/v1/threads/conv_8f21/events
Accept: text/event-stream
Authorization: Bearer $TOKEN

Authorization is enforced before the stream opens; an unauthorized caller never receives a stream. The connection is bound to one thread, and the internal owner key is stripped from every frame.

id: evt_7e0a4b123b214d56a8fe8f0e72e39d03
event: turn.ingested
data: {"eventId":"evt_7e0a…","type":"turn.ingested","threadId":"thr_2c53…",
       "occurredAt":"2026-07-31T04:40:03.041Z",
       "data":{"turnId":"msg_1","sequence":0,"participantId":"user","speakerType":"human"}}

Event catalogue — sixteen types

Reconnecting without losing events

Last-Event-ID: evt_7e0a4b123b214d56a8fe8f0e72e39d03

The hub keeps a replay buffer whose size is reported on connected. On reconnect, send the last id you processed — not the last you received — and events after it are replayed. Where you cannot set headers, ?lastEventId=evt_… does the same job.

Enabling Layer 2: LCC and ICCC

Layer 2 is never enabled implicitly. Requesting an engine requires its configuration block on the thread; requesting a mode without one is a 400.

PUT http://hwaichatanalysis.skoonline.org/api/v1/threads/conv_8f21/semantic-extension
{
  "enabled": true,
  "mode": "lcc",
  "interactionType": "tutorial_dyad",
  "lcc": {
    "referenceModelId": "rm_newton",
    "learnerParticipantIds": ["user"],
    "tutorParticipantIds": ["bot"],
    "classificationMethod": "hybrid"
  }
}

mode is none | lcc | iccc | lcc_and_iccc. Preconditions are enforced rather than assumed: a two-person chat does not qualify for LCC however long it runs, because LCC needs an instructional interactionType, a designated learner, a tutor role and a versioned reference model.

Reading analysis back

SSE tells you something changed; these endpoints tell you what it now is. Base path /api/v1. The full table, including research access and exports, is in the API reference.

Analysis

Owner retrieval and export

A signed URL is a delivery convenience issued after the ownership check. It is never treated as authorization.

Idempotency, retries and ordering

Idempotency is keyed on thread + turnId. Retrying with the same turnId returns 200 with the stored record and does not duplicate — which is what makes at-least-once delivery from your side safe, including a buffer flush that already partly succeeded.

Errors

One envelope for everything, echoing the request id — also returned as the X-Request-Id header — so you can correlate with server logs.

{
  "error": {
    "code": "validation_failed",
    "message": "Request validation failed.",
    "details": [{ "path": "participantId", "message": "must be an opaque identifier…" }],
    "requestId": "req_357d09bdbe9a45ae9329d7b02be119c2"
  }
}

Limits

All of these are configurable, so confirm the real values with this deployment's operator. GET /health and GET /ready report liveness and configuration readiness without disclosing secret values.

Reading the numbers honestly

This is the part of the contract most easily broken by a well-meaning UI. A measure describes how the interaction was distributed; a label like "engagement" or "mastery" on the same number is a claim the API has not made. The metric dictionary gives every measure alongside the interpretation it does not support — read the entry before you put the number on a screen.

Integration checklist

• Token carries application_client and act.sub / on_behalf_of
• threadId and turnId are stable ids from your own system
• Identifiers match [A-Za-z0-9][A-Za-z0-9_-]{0,127} and contain no personal information
• One POST per completed message — never per streamed token
• submittedAt, firstTokenAt and lastTokenAt captured during streaming
• The provider's own usage forwarded, not re-derived
• Ingestion is off the render path and cannot break the chat
• Retries reuse the same turnId; a 4xx is not retried
• Turns posted sequentially within a thread
• SSE consumed server-side with Last-Event-ID resume
• iccc.social_impact.revised invalidates any cached Social Impact
• null rendered as "not measurable", never 0
• not_applicable from LCC / ICCC handled as a valid answer

The rest of the documentation

This page is the fast path. 14 further documents cover what it summarises — the ownership model in full, every metric with the interpretation it does not support, the two Layer 2 engines, and the machine-readable contract.