API Quickstart

Viora is a labeling-as-a-service API: you POST a conversation (turn-by-turn or in one shot), Viora scores each turn for ten mental-health signals plus structured imminence fields, and returns a categorical R-level (R0 → R1-mid → R1-high → R2).

You define your own session and end-user identifiers. We accept what you send. Sessions and turns surface in your dashboard.

Get an API key

Ask your Viora admin to provision a tenant. You'll receive one key that looks like vrk_AbCdEf.... Treat it like a password — anyone with the key can submit traffic under your account.

Authentication

Every /v1/* request requires an Authorization header:

Authorization: Bearer vrk_AbCdEf...

Missing or wrong key returns 401.

Minimal end-to-end example

KEY="vrk_..."
BASE="https://viora.hyperfix.ai/api/v1"

# 1. create a session for one of your users
SID=$(curl -s -X POST -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"end_user_external_id":"user_42","title":"evening check-in"}' \
  "$BASE/sessions" | jq -r .id)

# 2. append a user turn
curl -s -X POST -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"role":"user","content":"I have been so anxious about work, I cant sleep"}' \
  "$BASE/sessions/$SID/messages"

The response includes prs (per-turn risk score), scores (per-signal continuous scores), r_level, and the rolled-up session_srs and session_r_level.

Real-time vs batch

Both work. For inline-gating (you call Viora before sending the bot's reply), POST one message at a time. For post-hoc analytics, you can submit the whole conversation as a stream of messages after the fact. Same endpoint either way.

Next steps