Backend Endpoints

API Structure

All SDK-facing APIs under /v1. Activity/ops APIs under /api.

/v1/events                    POST    Event ingestion
/v1/assistant/session/start   POST    Start voice session
/v1/assistant/session/stop    POST    Stop voice session
/v1/assistant/trigger/evaluate POST   Evaluate trigger policy
/v1/assistant/context/{id}    GET     Fetch session context
/v1/sdk/config                GET     SDK configuration

/api/activity                 GET     Activity stream
/api/activity/stream          GET     SSE activity stream
/api/features                 GET     Feature flags
/api/reengagement/{id}        GET     Reengagement status

/health                       GET     Health check

Event Ingestion

`POST /v1/events`

Primary event ingestion endpoint.

Request Body (EventIn):

{
  "user_id": "user-123",
  "session_id": "session-abc",
  "event": "validation_failed",
  "timestamp": 1710000000,
  "screen": "pan_entry",
  "screen_id": "pan_screen",
  "errors": ["pan_invalid"],
  "failure_reason_code": "pan_invalid",
  "component_id": "pan_field",
  "component_type": "text_input",
  "hint": "ABCDE****F",
  "masked": true,
  "client_id": "tenant-1",
  "mapping_version": "v1",
  "traceparent": "00-...",
  "trace_id": "trace-abc",
  "request_id": "req-123",
  "properties": {
    "validation_rule_id": "pan_format"
  }
}

Response:

{
  "status": "ok",
  "ingested_at": 1710000001
}

Event Types:

identity — User identification
screen_schema — Full schema registry
screen_schema_lazy — Minimal screen beacon
component_input — Redacted input hints
validation_failed — Field validation errors
error_reported — Generic errors
voice_conversation_turn — Agent telemetry

Behavior:

Creates/updates in-memory session by session_id
Sets latest_event to full payload
Updates screen from payload when present
Pushes to activity stream with trace

Assistant Session

`POST /v1/assistant/session/start`

Start voice session with LiveKit credentials.

Request Body (AssistantStartIn):

{
  "user_id": "user-123",
  "session_id": "session-abc",
  "screen": "pan_entry"
}

Response (AssistantStartOut):

{
  "token": "eyJ...",
  "livekit_url": "wss://livekit.example.com",
  "livekit_room": "kyc-room-session-abc",
  "expires_in_sec": 3600
}

Behavior:

Marks session active = True
Creates LiveKit room: {LIVEKIT_ROOM_PREFIX}-{session_id}
Dispatches agent via LiveKit Agent Dispatch
Generates participant JWT
Activity: session_start

Error Cases:

Missing LiveKit credentials → placeholder token
Missing screen context → missing_screen_context warning

`POST /v1/assistant/session/stop`

End voice session.

Request Body (AssistantStopIn):

{
  "session_id": "session-abc"
}

Response (AssistantStopOut):

{
  "session_id": "session-abc",
  "active": false
}

Behavior:

Sets session active = False
Evaluates reengagement recommendation
Activity: session_stop + reengagement

Trigger Evaluation

`POST /v1/assistant/trigger/evaluate`

Evaluate whether to offer assistance.

Request Body (TriggerEvaluateIn):

{
  "signals": {
    "screen": "pan_entry",
    "time_spent": 25,
    "errors": ["pan_invalid", "pan_invalid"],
    "idle_seconds": 5
  }
}

Response (TriggerEvaluateOut):

{
  "trigger": true,
  "reason": "high_time_spent",
  "action": "start_voice_agent",
  "intervention_mode": "voice_offer"
}

Trigger Rules (current implementation):

time_spent > 20 → trigger, reason high_time_spent
len(errors) >= 2 → trigger, reason repeated_errors
idle_seconds > 12 on critical step → trigger, reason idle_on_critical_step

Activity: kind: "trigger" with signals and decision.

Context Fetch

`GET /v1/assistant/context/{session_id}`

Fetch LLM context for voice agent.

Response:

{
  "session_id": "session-abc",
  "context": {
    "screen": "pan_entry",
    "latest_event": {...},
    "last_validation_failure": {...},
    "component_hints": [...],
    "kyc_kb": {...}
  },
  "system_prompt": "You are a KYC assistant..."
}

Behavior:

Loads session from store
Builds context from session + knowledge base
Generates system prompt for LLM
Synthetic activity: voice_agent_context_fetch

Voice Agent Context Refresh:

Periodic refresh: VOICE_CONTEXT_REFRESH_SECONDS (default 60)
User-turn refresh: VOICE_CONTEXT_REFRESH_ON_USER_TURN (default true)
Min interval: VOICE_CONTEXT_REFRESH_MIN_INTERVAL_SECONDS (default 5)

SDK Configuration

`GET /v1/sdk/config`

Fetch merged SDK configuration.

Headers:

X-KYCIS-SDK-Version: 1.0.0
X-Client-ID: your_client_id
X-API-Key: your_api_key (optional)

Response:

{
  "features": {
    "allow_multiple_assistant_prompt": false,
    "suppress_high_time_spent_trigger": false
  },
  "thresholds": {
    "min_trigger_interval_seconds": 60,
    "high_time_spent_seconds": 20
  },
  "metadata": {
    "version": "1.0.0",
    "source": "merged"
  }
}

Behavior:

Merges defaults with remote overrides
Returns features, thresholds, metadata
SDK refreshes periodically

Activity Stream

`GET /api/activity`

Query recent activity items.

Query Parameters:

limit — max items (default 100, max 1000)

Response:

{
  "items": [
    {
      "kind": "event",
      "timestamp": "2024-01-15T10:30:00Z",
      "session_id": "abc-123",
      "user_id": "user-456",
      "payload": {...},
      "trace": {
        "trace_id": "trace-abc",
        "request_id": "req-123"
      }
    }
  ],
  "livekit_ready": true,
  "feature_flags": {...}
}

Kinds:

event — Ingested events
trigger — Trigger evaluations
session_start — Voice session starts
session_stop — Voice session stops
reengagement — Reengagement recommendations
schema_push — Schema registry updates

`GET /api/activity/stream`

Server-sent events (SSE) for real-time updates.

Polling loop: 1 second intervals.

Feature Flags

`GET /api/features`

List current feature flag states.

Response:

{
  "flags": {
    "integration.livekit_dispatch": true,
    "trigger.v2_scoring": false,
    "integration.schema_registry": true
  }
}

Reengagement

`GET /api/reengagement/{session_id}`

Check reengagement recommendation.

Response:

{
  "recommended": true,
  "channel": "voice",
  "reason": "user_inactive_5min",
  "inactivity_seconds": 300
}

Health Check

`GET /health`

Backend health status.

Response:

{ "status": "ok" }

Headers

Required/standard headers:

Header	Required	Purpose
`Content-Type`	Yes	`application/json`
`X-API-Key`	If backend configured	API authentication
`traceparent`	Recommended	W3C trace context
`X-Request-ID`	Recommended	Request correlation
`X-KYCIS-SDK-Version`	SDK calls	SDK version
`X-Client-ID`	SDK calls	Multi-tenant routing

Error Responses

Standard HTTP status codes:

200 — Success
400 — Bad request (validation error)
401 — Unauthorized (invalid API key)
404 — Not found (session, endpoint)
422 — Unprocessable entity (Pydantic validation)
500 — Internal server error

Error body:

{
  "detail": "Error message"
}

Backend Endpoints

On this page