Elite Partner Integration Guide

What's new in v4.1 — voice profile catalogue expanded from 5 → 19 (named personas now supported: priya, aarav, ava, andrew, etc.); warm_female / warm_male upgraded to Azure HD multilingual voices; SSML xml:lang now auto-matches the voice locale (no more US-English phoneme drift on Indian-English voices); system_prompt is now honoured across all four scenario types (feynman, mock_interview, moot_court, roleplay — previously the last two silently dropped it). Backwards compatible — no migration needed for existing partners. Full version history at §14 Changelog.

TL;DR — minimum viable integration#

# 1. (one-time, admin) issue an API key
POST /api/v1/partners/{partner_id}/keys
Authorization: Bearer <admin_jwt>
{ "label": "production", "scopes": ["sessions:create", "sessions:list", "sessions:review"] }
# → returns plaintext key once: elite_live_sk_<32 hex>

# 2. (per student, your backend) mint a 1h session token
POST /api/v1/partners/sessions
X-Elite-Api-Key: elite_live_sk_<32 hex>
{
  "partner_student_ref": "your-stable-student-id",
  "interview_config": {
    "topic": "Kubernetes HPA",
    "scenario_type": "mock_interview",
    "difficulty": "intermediate",
    "voice_profile": "priya"
  }
}
# → returns { student_session_token, elite_session_id, feynman_start_url, voice_ws_url }

# 3. (in the student browser) call Elite directly with the token
POST /api/v1/feynman/sessions
Authorization: Bearer <student_session_token>
{}                                     # body can be empty — JWT carries the config

That's the whole API surface for a working interview. Sections below explain every field, error mode, and security guarantee in detail.

Table of Contents#

1. Overview
2. Architecture
3. Integration Flow
4. Getting Started
5. API Reference — Partner Control Plane
   • 5.1 POST /partners/sessions (mint a student token)
   • 5.2 interview_config field reference
   • 5.3 Partner prompt blocks (system_prompt, partner_context, …)
   • 5.4 Voice profile registry (19 profiles)
6. Student Data Plane — What the Browser Calls
7. Review Workflow
8. Student Browser Integration Patterns
9. Security Model
10. Rate Limits
11. Error Reference
12. Troubleshooting — The Three Mistakes Every Integrator Makes
13. Compliance & Privacy
14. Changelog

1. Overview#

Elite is a B2B API product. Your backend calls Elite APIs using an API key. Student browsers connect to Elite directly using short-lived session tokens that your backend provisions.

What your integration does:

• Your backend calls POST /api/v1/partners/sessions → gets a student_session_token
• You pass that token to your student's browser
• Student browser calls Elite APIs directly (Feynman, Vidya, voice, progress)

What never happens:

• API key is never exposed to the browser
• No iframe embed, no SSO, no postMessage handshake
• Your frontend is not the integration path — your backend is

2. Architecture#

Component Overview#

Data Boundary#

3. Integration Flow#

Session Lifecycle#

Token State Machine#

4. Getting Started#

Prerequisites#

• A server-side environment for making HTTPS calls (Node, Python, Go, etc.)
• An Elite admin account to issue API keys
• PARTNER_API_KEY_PEPPER must be set in the Elite backend .env before any keys are usable

Step 1 — Create a Partner Org (Admin)#

POST /api/v1/partners
Authorization: Bearer <admin_jwt>
Content-Type: application/json

{
  "slug": "devops-academy",
  "name": "DevOps Academy",
  "contact_email": "api@devopsacademy.com",
  "rate_limit_per_min": 120
}

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "devops-academy",
  "name": "DevOps Academy",
  "created_at": "2026-04-16T10:00:00Z"
}

Step 2 — Issue an API Key (Admin)#

POST /api/v1/partners/{partner_id}/keys
Authorization: Bearer <admin_jwt>
Content-Type: application/json

{
  "label": "production-key",
  "scopes": ["sessions:create", "sessions:list", "sessions:review", "courses:generate", "mock_interviews:create", "students:read", "students:delete"],
  "rate_limit_per_min": 120
}

Response (plaintext key shown once only — store immediately):

{
  "id": "key-uuid",
  "key": "elite_live_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "key_prefix": "elite_live_sk_a1b2c3d4",
  "label": "production-key",
  "scopes": ["sessions:create", "sessions:list", "sessions:review", "courses:generate", "mock_interviews:create", "students:read", "students:delete"],
  "created_at": "2026-04-16T10:00:00Z",
  "warning": "Store this key securely — it will not be shown again."
}

Key format: elite_<env>_sk_<32 hex chars> · Prefix (non-secret, shown in UI): first 8 hex chars

Elite stores only HMAC-SHA-256(server_pepper, key) — the plaintext is never persisted and cannot be recovered. If lost, revoke and reissue.

Tip: Register the prefix pattern elite_live_sk_ with GitHub Secret Scanning to get automatic alerts if a key leaks to a public repo.

Step 3 — Configure Environment#

# Server-side only — never commit, never log, never send to the browser
ELITE_API_KEY=elite_live_sk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
ELITE_BASE_URL=https://api.elite.pankh.ai

Step 4 — Create a Student Session (Your Backend)#

// Node.js / TypeScript — server-side only
const response = await fetch(`${process.env.ELITE_BASE_URL}/api/v1/partners/sessions`, {
  method: 'POST',
  headers: {
    'X-Elite-Api-Key': process.env.ELITE_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    partner_student_ref: 'your-internal-user-id-123', // opaque ID — not PII
    display_name: 'Priya Sharma',                      // optional
    scopes: ['feynman', 'voice', 'courses'],
  }),
});

if (!response.ok) {
  const err = await response.json();
  throw new Error(`Elite session error: ${err.error?.code} — ${err.error?.message}`);
}

const { student_session_token, session_id, expires_at } = await response.json();
// Pass student_session_token to your frontend — see Section 6 for secure patterns

# Python (httpx) — server-side only
import httpx

resp = httpx.post(
    f"{ELITE_BASE_URL}/api/v1/partners/sessions",
    headers={"X-Elite-Api-Key": ELITE_API_KEY},
    json={
        "partner_student_ref": "your-internal-user-id-123",
        "display_name": "Priya Sharma",
        "scopes": ["feynman", "voice", "courses"],
    },
    timeout=10.0,
)
resp.raise_for_status()
data = resp.json()
student_session_token = data["student_session_token"]

Step 5 — Student Browser Uses the Token#

// Browser — use student_session_token for all Elite API calls.
// POST /api/v1/feynman/sessions is the canonical REST endpoint;
// /api/v1/feynman/start is the legacy alias and still works.
const response = await fetch(`${ELITE_BASE_URL}/api/v1/feynman/sessions`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${studentSessionToken}`,
    'Content-Type': 'application/json',
  },
  // Body can be empty when interview_config was passed at mint time —
  // the JWT carries topic/difficulty/scenario_type/voice_profile/etc.
  body: JSON.stringify({}),
});

5. API Reference#

Base URL#

https://api.elite.pankh.ai/api/v1/partners

Authentication — Two Tiers#

Admin Endpoints#

POST /partners — Create Partner Org#

// Request
{
  "slug": "string (2–60 chars, a-z0-9- only)",
  "name": "string",
  "contact_email": "string | null",
  "rate_limit_per_min": 60,
  "metadata": {}
}

GET /partners — List All Partners#

Returns { partners: [...], count: N }

GET /partners/{partner_id} — Partner Detail + Keys#

Returns partner info and key list. Key hashes are never returned — only key_prefix, scopes, and metadata.

POST /partners/{partner_id}/keys — Issue API Key#

// Request
{
  "label": "string | null",
  "scopes": ["sessions:create", "sessions:list", "sessions:review", "courses:generate", "mock_interviews:create", "students:read", "students:delete"],
  "rate_limit_per_min": 120,
  "expires_at": "2027-01-01T00:00:00Z"
}

// Response (key shown ONCE — store immediately)
{
  "id": "uuid",
  "key": "elite_live_sk_...",
  "key_prefix": "elite_live_sk_a1b2c3d4",
  "scopes": ["sessions:create", "sessions:list", "sessions:review", "courses:generate", "mock_interviews:create", "students:read", "students:delete"],
  "created_at": "...",
  "warning": "Store this key securely — it will not be shown again."
}

DELETE /partners/{partner_id}/keys/{key_id} — Revoke Key#

// Request body (optional)
{ "reason": "Rotation — quarterly policy" }

// Response
{ "id": "uuid", "revoked_at": "2026-04-16T10:30:00Z" }

Revoked keys fail immediately on next use with 401 PARTNER_KEY_REVOKED. There is no grace period.

Partner-Facing Endpoints#

POST /partners/sessions — Create Student Session Token#

Auth: X-Elite-Api-Key with sessions:create scope

// Request
{
  "partner_student_ref": "string — your opaque student ID, 1-500 chars, not PII",
  "display_name": "string | null",
  "scopes": ["feynman", "voice", "courses"],
  "metadata": {},

  // Top-level convenience aliases (v4.2) — you can send voice_profile,
  // system_prompt, and partner_context at the root instead of nesting them
  // inside interview_config. Both locations work; interview_config wins if
  // the same field appears in both places.
  "voice_profile": "brian",
  "system_prompt": "You are an energetic DevOps coach with 50 years of experience...",
  "partner_context": "Learners in this cohort have 3+ years of experience.",

  "interview_config": {
    "topic": "Kubernetes HPA for Kafka workloads",
    "difficulty": "intermediate",
    "scenario_type": "mock_interview",
    "domain": "tech",
    "company": "Stripe",
    "job_description": "Senior SRE — must know distributed systems, K8s, Kafka",
    "max_exchanges": 8,

    // Partner prompt customisation (v4.0 — all optional, all bounded, all
    // injection-scanned at mint time).
    "user_background": "4th-year CS undergrad. Strong in Go and Python. New to K8s internals.",
    "learning_goal": "Pass a senior SRE loop by explaining HPA from first principles.",
    "topic_focus": ["custom metrics API", "stabilization windows", "pod disruption budgets"],
    "partner_context": "Acme Bootcamp — Spring 2026 Distributed Systems cohort.",
    "system_prompt": "Push hard on production failure modes. Do not accept textbook answers.",
    "voice_profile": "warm_female"
  }
}

All interview_config fields are optional. Anything set here lands in the student JWT's claims and is automatically injected when the student calls POST /feynman/sessions with an empty or partial body. Use this — pre-tagging the interview at mint time is the difference between a clean API surface and a sessionId-juggling mess.

Top-level aliases (v4.2): voice_profile, system_prompt, and partner_context can be sent at the root of the request body instead of inside interview_config. This is a convenience for partners whose integration maps these as flat fields. If the same field appears at both the root and inside interview_config, the interview_config value takes precedence. All validation (allowlist, injection scan, length caps) applies identically regardless of where the field is sent.

interview_config field reference#

How partner prompt blocks are assembled#

Partner context is injected between the identity block and the platform rules block. The ordering is not configurable — platform rules always win.

[IDENTITY BLOCK]           ← interviewer persona, company, difficulty
[PARTNER CONTEXT]          ← partner_context (advisory)
[LEARNER BACKGROUND]       ← user_background + learning_goal
[TOPIC FOCUS]              ← topic_focus[]
[PARTNER INSTRUCTIONS]     ← system_prompt (advisory — platform rules below supersede)
[PLATFORM RULES]           ← STAY-ON-TOPIC, EVALUATION_READY, PROMPT-INJECTION RESISTANCE

If the LLM is asked to ignore platform rules via partner text, the system is designed to treat that as an adversarial signal — the partner block is explicitly labelled "advisory" and the stay-on-topic / injection-resistance rules live below it.

Scenario coverage. As of v4.1, partner blocks are rendered for all four scenario_type values: feynman, mock_interview, moot_court, roleplay. Earlier builds silently dropped system_prompt / partner_context / user_background / topic_focus / learning_goal for moot_court and roleplay — that's now fixed. If you're integrating against either of those scenarios and previously worked around the gap by re-stating context inside topic, you can move that text back into the proper structured fields.

Injection scan — what gets rejected#

Every free-text partner field (system_prompt, partner_context, user_background, learning_goal, job_description, company) is scanned at POST /partners/sessions time against a pattern set. Matches return 422 VALIDATION_ERROR with context.field pointing at the offending field — the JWT is never minted.

Blocked patterns include (non-exhaustive):

• ignore / disregard / forget … previous / prior / above instructions / prompts / rules
• <<SYS>>, [INST], <|im_start|>, <|im_end|>
• ### SYSTEM: or ### INSTRUCTIONS: headers
• Role-break attempts: you are now …, pretend to be …, act as … followed by privileged roles
• Prompt-reveal attempts: reveal / print your (system) prompt / instructions / rules
• jailbreak mode / jailbreak prompt

Benign text — learner context, topical focus, partner branding, "push hard on safety proofs" — passes cleanly.

Voice profile registry#

19 profiles total — pick from generic role-style names or named personas. Server resolves each to an Azure Neural voice (TTS path), a gpt-4o-realtime voice (live voice path), and a BCP-47 lang tag for SSML xml:lang (so Indian-English voices get en-IN phoneme selection and US-English voices get en-US).

Generic profiles (stable contract, recommended when you don't care about identity):

Indian-English personas:

US-English personas (HD / Multilingual — least synthetic):

Unknown voice_profile values return 422 VALIDATION_ERROR. The catalogue is also reachable at runtime via GET /api/v1/voice/profiles so your UI can render a picker without duplicating the map.

Picking the right profile

• For Indian-English learner-facing tone, prefer priya / ananya (female) or aarav / ritesh / kunal (male). All use en-IN phoneme selection automatically.
• For US-English with the smallest "robotic" feel, prefer ava / andrew (HD), then emma / brian, then jenny / ryan.
• For interview/evaluator contexts, authoritative (Davis) reads more formal than the HD voices.
• The persona names are display-only — the underlying Azure voice is what matters for tone and naturalness. If your UI labels personas differently (e.g. "Aarushi" instead of "ananya"), map your label to the voice_profile enum on your side; the enum value is what travels in the JWT.

// Response (201)
{
  "student_session_token": "eyJhbGci...",               // 1h TTL HS256 JWT — hand to browser
  "session_id": "550e8400-e29b-41d4-a716-446655440000",  // the Elite session UUID
  "elite_session_id": "550e8400-e29b-41d4-a716-446655440000",  // alias of session_id — store this
  "partner_student_ref": "your-user-123",
  "internal_user_id": null,                              // null for partner sessions (no Elite account)
  "expires_at": "2026-04-20T11:00:00Z",
  "pankh_base_url": "https://api.elite.pankh.ai",
  "feynman_start_url": "https://api.elite.pankh.ai/api/v1/feynman/sessions",
  "feynman_exchange_url": "https://api.elite.pankh.ai/api/v1/feynman/exchange",
  "feynman_evaluate_url": "https://api.elite.pankh.ai/api/v1/feynman/evaluate",
  "voice_ws_url": "wss://api.elite.pankh.ai/api/v1/voice/ws"
}

⚠ Critical — what session_id / elite_session_id is used for: This UUID is the identifier for the interview. Every downstream call that references the interview uses it:

• POST /feynman/exchange → { "sessionId": "<this UUID>", "message": "..." }
• POST /feynman/evaluate → { "sessionId": "<this UUID>" }
• GET /feynman/{session_id} → report retrieval (student side)
• GET /partners/students/{ref}/sessions/{session_id} → report retrieval (partner side)
• PATCH /partners/sessions/{session_id}/review → instructor review

Do not substitute it with your own internal session ID. If you do, Elite returns 422 VALIDATION_ERROR with a message pointing you back to this field.

Student token scopes (encoded into the JWT):

Idempotency: If partner_student_ref already exists, the same internal mapping is reused and a fresh token is minted. No duplicate student records are created.

GET /partners/students — List Students#

Auth: X-Elite-Api-Key with students:read scope

Query params: limit (1–200, default 50), offset (default 0)

// Response
{
  "students": [
    {
      "id": "uuid",
      "partner_student_ref": "your-user-123",
      "display_name": "Priya Sharma",
      "internal_user_id": "uuid",
      "metadata": {},
      "created_at": "2026-04-10T08:00:00Z",
      "updated_at": "2026-04-15T14:22:00Z"
    }
  ],
  "limit": 50,
  "offset": 0
}

DELETE /partners/students/{partner_student_ref} — Remove Student Mapping#

Auth: X-Elite-Api-Key with students:delete scope

Used for GDPR / offboarding. Removes the partner → internal user mapping. Active session tokens for this student continue to work until their 1h TTL expires.

// Response
{ "deleted": true, "partner_student_ref": "your-user-123" }

GET /partners/students/{partner_student_ref}/sessions — List a Student's Interview Sessions#

Auth: X-Elite-Api-Key with sessions:list scope

Query params: limit (1–200, default 50), offset (default 0)

// Response (200)
{
  "sessions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "topic": "Kubernetes HPA",
      "status": "completed",            // active | completed | abandoned
      "review_status": "published",      // null | pending_review | reviewed | published
      "overall_score": 78,
      "created_at": "2026-04-20T10:55:32Z",
      "completed_at": "2026-04-20T11:12:05Z"
    }
  ],
  "partner_student_ref": "your-user-123",
  "limit": 50,
  "offset": 0
}

Use this to drive your instructor dashboard — sort by created_at DESC, filter by review_status='pending_review' to find interviews waiting for a grade.

GET /partners/students/{partner_student_ref}/sessions/{session_id} — Get Full Session Report#

Auth: X-Elite-Api-Key with sessions:list scope · session_id must be a UUID (returns 422 otherwise)

Gating: Returns 403 FORBIDDEN until an instructor publishes the session via PATCH /partners/sessions/{id}/review. This is a deliberate gate — AI scores are never surfaced to the partner until a human instructor signs off.

// Response (200 — only when review_status='published')
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "topic": "Kubernetes HPA",
  "status": "completed",
  "review_status": "published",
  "partner_student_ref": "your-user-123",
  "instructor_notes": "Strong on pod scheduling; vague on custom metrics API.",
  "transcript": [
    { "role": "assistant", "content": "Explain how HPA scales based on custom metrics..." },
    { "role": "user", "content": "HPA queries the metrics API..." }
  ],
  "scorecard": {
    "overall_score": 78,
    "clarity": 82,
    "accuracy": 75,
    "completeness": 70,
    "depth": 85,
    "key_concepts_expected": ["HPA control loop", "custom metrics adapter", "stabilization windows"],
    "key_concepts_covered": ["HPA control loop", "custom metrics adapter"],
    "concepts_missed": ["stabilization windows"],
    "mistakes_presented": [],
    "mistakes_caught": [],
    "feedback": "Candidate demonstrated strong grasp of autoscaler primitives..."
  },
  "exchange_count": 8,
  "duration_seconds": 927,
  "created_at": "2026-04-20T10:55:32Z",
  "completed_at": "2026-04-20T11:12:05Z"
}

// Response (403 — not yet published)
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Session results not yet published by instructor",
    "status": 403,
    "context": { "review_status": "pending_review" }
  }
}

PATCH /partners/sessions/{session_id}/review — Instructor Review Action#

Auth: X-Elite-Api-Key with sessions:review scope · session_id must be a UUID

Drives the review state machine. See Section 7 — Review Workflow for the full flow.

// Request
{
  "action": "publish",                  // "publish" | "flag"
  "instructor_notes": "Strong on pod scheduling; vague on custom metrics API."
}

// Response (200)
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "review_status": "published"
}

Self-Serve Key Minting (Allowlisted Emails)#

For partners onboarding developers who should be able to mint their own 30-day keys without admin intervention, Elite supports a per-email allowlist.

GET /partners/self-serve/me — Check Self-Serve Eligibility#

Auth: Supabase Bearer <jwt> (end-user, not an API key)

// Response (200 — eligible)
{
  "email": "dev@partner.com",
  "eligible": true,
  "partner_ids": ["d08484e4-ee8e-47ba-acef-9e560a0fc058"],
  "default_ttl_days": 30,
  "max_active_keys": 3,
  "active_keys": 1
}

// Response (200 — not eligible)
{ "email": "dev@partner.com", "eligible": false, "reason": "email_not_allowlisted" }

POST /partners/self-serve/keys — Mint a 30-Day Key#

Auth: Supabase Bearer <jwt> of an allowlisted email

// Request
{
  "partner_id": "d08484e4-ee8e-47ba-acef-9e560a0fc058",
  "label": "my-integration-test"
}

// Response (201 — key shown ONCE)
{
  "id": "key-uuid",
  "key": "elite_dev_sk_...",
  "key_prefix": "elite_dev_sk_a1b2c3d4",
  "scopes": ["sessions:create", "sessions:list", "sessions:review", "students:read", "students:delete"],
  "expires_at": "2026-05-20T10:00:00Z",
  "warning": "Store this key securely — it will not be shown again."
}

Denial reasons returned as 403 PARTNER_SELF_SERVE_DENIED:

• email_not_allowlisted
• partner_not_in_allowlist (email is allowlisted, but not for this specific partner_id)
• max_active_keys_reached (revoke an existing key first)

Admin Endpoints — Self-Serve Allowlist#

GET /partners/admin/self-serve-allowlist — List Allowlist#

Auth: Admin JWT

Returns all allowlisted emails with their per-email config (allowed partners, TTL, key cap).

POST /partners/admin/self-serve-allowlist — Upsert Email Entry#

// Request
{
  "email": "dev@partner.com",
  "partner_ids": ["d08484e4-ee8e-47ba-acef-9e560a0fc058"],
  "default_ttl_days": 30,
  "max_active_keys": 3
}

DELETE /partners/admin/self-serve-allowlist/{email} — Revoke Email Entry#

Cascades: revokes any active self-serve keys the email had minted.

6. Student Data Plane — What the Browser Calls#

Once your backend mints a student_session_token, the student browser uses Authorization: Bearer <student_session_token> to call Elite directly. Every endpoint below works with the partner JWT — no Elite account required, no PRO subscription check (partner students are auto-bypassed).

Feynman — Text Interview (REST + SSE)#

POST /api/v1/feynman/sessions — Start the Interview#

REST alias for the older /feynman/start. Body can be empty when interview_config was passed at mint time; otherwise pass the topic/config here.

// Request (minimal — relies on JWT claims)
{}

// Request (explicit — overrides JWT claims)
{
  "topic": "Kubernetes HPA",
  "difficulty": "intermediate",
  "mode": "testing",
  "maxExchanges": 8,
  "company": "Stripe",
  "jobDescription": "Senior SRE role..."
}

// Response (201)
{
  "session_id": "550e8400-...",     // UUID — use this as sessionId in subsequent calls
  "opening_message": "Explain how Kubernetes HPA scales pods based on custom metrics...",
  "mode": "testing"
}

POST /api/v1/feynman/exchange — Send a Turn, Stream the Reply#

Returns an SSE stream. Use fetch() + ReadableStream — not EventSource (no Authorization header support, token-in-URL is a leak vector).

// Request
{
  "sessionId": "550e8400-...",      // ⚠ UUID, NOT your internal session ID
  "message": "HPA queries the metrics API on a control loop..."
}

SSE event shape:

data: {"token": "That's"}
data: {"token": " a great"}
data: {"token": " start..."}
data: {"done": true, "session_id": "550e8400-...", "exchange_number": 3}

POST /api/v1/feynman/evaluate — End the Interview, Get Scorecard#

// Request
{ "sessionId": "550e8400-..." }

// Response (200)
{
  "session_id": "550e8400-...",
  "score": 78,
  "feedback": "..."
}

Side effect: if the session was minted with a partner key, Elite atomically sets review_status='pending_review' so it shows up on your instructor dashboard.

GET /api/v1/feynman/{session_id} — Get Session Detail#

Partner-scoped lookup — returns only sessions where partner_id + partner_student_ref match the JWT claims.

GET /api/v1/feynman/history/list — List This Student's Sessions#

Returns the sessions owned by this specific partner_student_ref (not every session for the partner).

Voice — WebSocket PTT + REST Fallbacks#

wss://.../api/v1/voice/ws — Push-to-Talk Voice WebSocket#

The primary voice path. Auth is via the first message after connect, not a query parameter.

# Client → Server (first frame, JSON)
{ "type": "auth", "token": "<student_session_token>" }

# Server → Client (after auth)
{ "type": "session_started", "session_id": "...", "topic": "Kubernetes HPA" }

# Client → Server (push-to-talk held — binary audio chunks)
<base64 PCM16 16kHz audio frames wrapped in { "type": "audio_chunk", "data": "..." }>

# Client → Server (PTT released)
{ "type": "end_turn" }

# Server → Client (streaming audio reply)
<binary frames of the AI's synthesized audio>

# Client → Server (student ends the call)
{ "type": "end_session" }

Common close codes:

POST /api/v1/voice/synthesize — Text → Audio (REST)#

Fallback for when you can't hold a WebSocket open. Returns audio/mpeg bytes.

// Request
{ "text": "Hello, welcome to the interview.", "voice": "en-US-AriaNeural" }

Response: Content-Type: audio/mpeg, raw MP3 body.

Speech-safe guarantee (v4.0) — the backend normalises text before synthesis. Your UI can safely send raw model output containing markdown, LaTeX, URLs, emoji, tables, footnotes, or code fences — none of it will be read aloud. Specifically:

• Markdown markers (#, **, _, ~~, bullets, blockquotes) are stripped.
• LaTeX delimiters ($ … $, $$ … $$, \( … \), \[ … \]) are removed and common macros (\frac, \sqrt, \pi, ^2 / ^3) are expanded to words.
• URLs are collapsed to "link" rather than recited.
• Mid-sentence hashtags (#important) become the bare word; #N becomes "number N".
• Emojis and symbol-class codepoints are dropped.
• Code fences become a single "code block." interjection.

If normalisation strips the input to empty (e.g. "only emojis") the endpoint returns 422 VALIDATION_ERROR with message: "nothing to synthesise after normalisation" instead of synthesising silence.

If you pass voice explicitly, that voice wins. Otherwise the server picks the Azure Neural voice registered against the session's voice_profile (set via partner interview_config.voice_profile). Your frontend can read session.voice_profile from the POST /feynman/sessions response and map it locally, or simply omit the voice field and let the server choose.

GET /api/v1/voice/profiles — Voice Profile Catalogue#

Auth: any valid bearer (partner student JWT or Elite user JWT).

Returns the full list of voice profiles so your UI can render a picker without hardcoding the map. As of v4.1 there are 19 profiles across three groups: generic role-style names, Indian-English personas, US-English personas (HD / multilingual). See §5.4 Voice profile registry for the full table including underlying Azure voice and BCP-47 language tag.

// Response (200) — abbreviated; full response has all 19 entries
{
  "profiles": [
    { "id": "neutral",       "display_name": "Neutral (default)",        "prosody_rate": "medium",
      "notes": "Current production default — zero-migration for existing partners." },
    { "id": "warm_female",   "display_name": "Warm Female",              "prosody_rate": "medium",
      "notes": "Calm, approachable. Suits tutoring and learner-facing contexts." },
    { "id": "warm_male",     "display_name": "Warm Male",                "prosody_rate": "medium" },
    { "id": "authoritative", "display_name": "Authoritative",            "prosody_rate": "medium",
      "notes": "Higher gravitas. Suits interview and evaluator contexts." },
    { "id": "energetic",     "display_name": "Energetic",                "prosody_rate": "fast" },

    // Indian-English personas — all use en-IN phoneme selection
    { "id": "priya",         "display_name": "Priya (Indian female)",    "prosody_rate": "medium",
      "notes": "Warm Indian-English female persona." },
    { "id": "ananya",        "display_name": "Ananya (Indian female)",   "prosody_rate": "medium",
      "notes": "Expressive Indian-English female persona." },
    { "id": "kavya",         "display_name": "Kavya (Indian female)",    "prosody_rate": "medium" },
    { "id": "aarav",         "display_name": "Aarav (Indian male)",      "prosody_rate": "medium" },
    { "id": "ritesh",        "display_name": "Ritesh (Indian male)",     "prosody_rate": "medium",
      "notes": "Indian-English male persona (backed by en-IN-PrabhatNeural)." },
    { "id": "kunal",         "display_name": "Kunal (Indian male)",      "prosody_rate": "medium" },
    { "id": "rehaan",        "display_name": "Rehaan (Indian male)",     "prosody_rate": "medium" },

    // US-English HD / multilingual personas — least synthetic
    { "id": "ava",           "display_name": "Ava (US female, HD)",      "prosody_rate": "medium",
      "notes": "Azure HD multilingual voice. Most natural-sounding female." },
    { "id": "andrew",        "display_name": "Andrew (US male, HD)",     "prosody_rate": "medium",
      "notes": "Azure HD multilingual voice. Most natural-sounding male." },
    { "id": "emma",          "display_name": "Emma (US female, expressive)",  "prosody_rate": "medium" },
    { "id": "brian",         "display_name": "Brian (US male, expressive)",   "prosody_rate": "medium" },
    { "id": "jenny",         "display_name": "Jenny (US female, multilingual)", "prosody_rate": "medium" },
    { "id": "ryan",          "display_name": "Ryan (US male, multilingual)",   "prosody_rate": "medium" },
    { "id": "jack",          "display_name": "Jack (US male)",           "prosody_rate": "medium",
      "notes": "US-English male persona (backed by Andrew HD)." }
  ],
  "default": "neutral"
}

The concrete Azure Neural voice and gpt-4o-realtime voice each profile maps to are not part of the public contract — they can be tuned or swapped without breaking partners. Integrate against the profile id, not the underlying voice name.

SSML xml:lang is auto-derived (v4.1). When /voice/synthesize runs, the server reads the locale prefix from the resolved Azure voice (e.g. en-IN-NeerjaNeural → xml:lang='en-IN', en-US-AvaMultilingualNeural → xml:lang='en-US'). Previously this was hardcoded to en-US, which forced Indian-English voices through US phoneme selection and amplified the "robotic" complaint. Partners don't need to set anything — just pick the right voice_profile.

POST /api/v1/voice/transcribe — Audio → Text (REST)#

Multipart form upload of a single audio file. Returns the transcript.

7. Review Workflow#

Every partner-owned interview flows through a four-state machine before the partner can retrieve the report. This keeps the instructor — not the AI — as the gate.

Why the gate: AI scores are directional, not authoritative. A human instructor attaches instructor_notes during publish, providing the qualitative context that the score alone can't carry. Partners see the scorecard only when the instructor stands behind it.

8. Student Browser Integration#

Token Passing Patterns#

Option A — HTTP-only cookie (recommended)

// Your backend sets cookie after creating session
res.cookie('elite_token', student_session_token, {
  httpOnly: true,   // not accessible to JS — XSS-safe
  secure: true,     // HTTPS only
  sameSite: 'strict',
  maxAge: 3600 * 1000, // match Elite's 1h TTL
});

Option B — In-memory only (acceptable)

// Your backend returns token in authenticated JSON response
// Frontend stores in memory only — NOT localStorage, NOT sessionStorage
const { eliteToken } = await yourApi.startSession(userId);
// eliteToken lives only in JS closure — clears on page reload

Never store student_session_token in localStorage or sessionStorage. These are accessible to any JavaScript on the page (XSS risk). HTTP-only cookie or in-memory are the only safe options.

Making Elite API Calls from Browser#

class EliteClient {
  constructor(private token: string) {}

  async startFeynman(topic?: string): Promise<Response> {
    return fetch(`${ELITE_BASE_URL}/api/v1/feynman/sessions`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.token}`,
        'Content-Type': 'application/json',
      },
      // Body can be empty when interview_config was set at mint time —
      // the JWT carries topic / scenario_type / voice_profile / etc.
      // Passing an explicit topic here overrides the JWT claim.
      body: JSON.stringify(topic ? { topic } : {}),
    });
  }

  // SSE streaming (Feynman exchange, course generation)
  // WARNING: EventSource does not support Authorization headers.
  // Do NOT pass the token as a query parameter — it will appear in server logs,
  // browser history, and Referer headers.
  // Use a POST endpoint that upgrades to SSE, or a server-sent proxy via your backend.
  streamExchange(sessionId: string, message: string): EventSource {
    // Correct pattern: POST first to get a short-lived stream ticket,
    // then open EventSource with the ticket ID (not the full JWT)
    throw new Error('See POST /api/v1/feynman/exchange — returns SSE directly, no EventSource needed');
  }
}

SSE and auth: Elite's streaming endpoints (/feynman/exchange, /vidya/classrooms) use POST + StreamingResponse — not EventSource. Use fetch() with Authorization: Bearer and read the response body as a stream. This avoids the token-in-URL problem entirely.

Token Expiry Handling#

async function withTokenRefresh<T>(
  call: () => Promise<Response>,
  refreshToken: () => Promise<string>,  // calls your backend, which calls POST /partners/sessions
): Promise<T> {
  let response = await call();

  if (response.status === 401) {
    const err = await response.json();
    if (err.error?.code === 'EXPIRED_TOKEN') {
      const newToken = await refreshToken();
      eliteClient = new EliteClient(newToken);
      response = await call();
    } else {
      throw new Error(`Auth error: ${err.error?.code}`);
    }
  }

  if (!response.ok) {
    const err = await response.json();
    throw new Error(`Elite API error ${response.status}: ${err.error?.code}`);
  }

  return response.json();
}

9. Security Model#

Threat Model#

Key Rotation Policy (Recommended)#

• Frequency: Quarterly minimum, or immediately on team member offboarding
• Zero-downtime: Issue new key → deploy → verify → revoke old key (overlap is safe)
• Never: Reuse revoked keys. Always issue a fresh key.

Audit Log#

Every API key call appends a row to partner_api_audit_log (retained 90 days):

{
  "partner_id": "uuid",
  "api_key_id": "uuid",
  "endpoint": "/partners/sessions",
  "http_method": "POST",
  "status_code": 201,
  "duration_ms": 45,
  "partner_student_ref": "your-user-123",
  "timestamp": "2026-04-16T10:00:00Z"
}

Contact partnerships@pankh.ai to request an audit log export.

10. Rate Limits#

Rate limiting uses a Redis sliding window (60-second window). When the limit is hit:

HTTP 429 Too Many Requests
Retry-After: 60

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Partner rate limit exceeded (60 req/min)",
    "status": 429,
    "context": { "retry_after_seconds": 60 }
  }
}

Always respect Retry-After. Implement exponential backoff for retries.

11. Error Reference#

Error Envelope#

All errors from the Elite API use this consistent structure:

{
  "error": {
    "code": "MACHINE_READABLE_CODE",
    "message": "Human-readable description",
    "status": 401,
    "context": {}
  }
}

Error Codes#

12. Troubleshooting#

Three mistakes account for 90% of first-time integration pain. Check these before opening a support ticket.

12.1 "I got a 500 INTERNAL_ERROR on /feynman/exchange or /feynman/evaluate"#

Almost certainly: you sent your internal session ID as sessionId instead of the Elite UUID.

// WRONG — your Pankh/LMS internal session id is not a UUID
{ "sessionId": "EkNREKAZzYkGlU4eRNLswA", "message": "..." }

// RIGHT — use session_id / elite_session_id from POST /partners/sessions response
{ "sessionId": "550e8400-e29b-41d4-a716-446655440000", "message": "..." }

Elite now validates this at the boundary and returns 422 VALIDATION_ERROR with a message pointing back to the correct field. If you still see a 500 on this endpoint, the likely cause is an older deploy — retry after a few minutes and capture the full response body, not just the status code.

12.2 "The browser console says CORS failure"#

Usually not CORS. The browser shows a generic TypeError: Failed to fetch or "no response" message whenever a request gets a non-2xx with an error body it couldn't parse as expected. To confirm:

1. Open DevTools → Network tab.
2. Find the failing request and look at the Status Code and Content-Length.
3. If Status Code is 500, 403, 422, etc. and Content-Length is non-zero, the response actually arrived — it's an Elite-side error, not CORS.
4. Real CORS rejection shows Content-Length 0, no body, and a specific Access-Control-Allow-Origin-related error in the DevTools console.

If it is genuinely CORS: your origin needs to be added to Elite's allowed list. Send the exact origin (scheme + host + port) to partnerships@pankh.ai.

12.3 "My student gets 403 PRO subscription required"#

Not anymore. Partner students are auto-bypassed from Elite's PRO tier check on all data-plane endpoints (/feynman/*, /voice/*, /courses/*, /coding/*, etc.). Your partner org paid — individual students don't need Elite accounts.

If you're seeing this error on a request from a partner JWT, either:

• The JWT was minted before this fix shipped (pre-2026-04-20). Re-mint the token via POST /partners/sessions.
• The request is going without the Authorization: Bearer <jwt> header. Check that your browser attached it.
• The JWT is expired (1h TTL) — call POST /partners/sessions again from your backend.

12.4 "I published a session but the GET still returns 403"#

Confirm the PATCH /sessions/{id}/review call used action: "publish" (not "flag"). flag sets review_status='reviewed', which is still not published. Only publish opens the gate.

# Check current review_status
curl -H "X-Elite-Api-Key: $KEY" \
  "https://api.elite.pankh.ai/api/v1/partners/students/your-ref/sessions" \
  | jq '.sessions[] | {id, review_status}'

12.5 "My self-serve key mint returns 403 PARTNER_SELF_SERVE_DENIED"#

GET /partners/self-serve/me first — the response tells you exactly why:

• email_not_allowlisted — ask your Elite admin to add your email via POST /partners/admin/self-serve-allowlist.
• partner_not_in_allowlist — your email is allowed for other partners but not this partner_id. Check the partner_ids array in the allowlist entry.
• max_active_keys_reached — revoke an old key before minting a new one.

12.6 "Report GET /students/{ref}/sessions/{id} returns 500 right after we integrated"#

If you see a 500 (not 403) and the body is {"error":{"code":"INTERNAL_ERROR",...}}, tell us the request ID from the x-request-id response header. Elite logs every 500 with that correlation ID and we can trace it in under a minute.

Before 2026-04-20 this endpoint could 500 because the service queried non-existent columns (scorecard, transcript). That's fixed — report now returns transcript[] + a structured scorecard{} object.

12.7 "I got a 422 with contains a pattern we block"#

You sent a partner free-text field (system_prompt, partner_context, user_background, learning_goal, job_description, company) whose content matched Elite's prompt-injection pattern set.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "interview_config.system_prompt contains a pattern we block to prevent prompt injection (e.g. 'ignore previous instructions', role-break attempts, system markers).",
    "status": 422,
    "context": { "field": "system_prompt" }
  }
}

How to fix: rewrite the field using descriptive, positive-voice guidance rather than meta-instructions.

Partner text is always rendered below an advisory header — platform stay-on-topic and prompt-injection-resistance rules are below partner context in the system prompt and take precedence regardless. If you need behaviour we block, tell us what you're trying to achieve and we'll find a safe route: partnerships@pankh.ai.

13. Compliance & Privacy#

Data Retained by Elite#

Your Obligations#

1. User consent — Disclose AI-powered tutoring in your privacy policy.
2. Data minimisation — partner_student_ref must be an opaque ID (UUID, hash), not PII (email, name, national ID).
3. Key rotation — Rotate API keys quarterly or on team member offboarding.
4. Token handling — Do not log, persist, or proxy student_session_token values. Treat them as passwords.
5. Secret scanning — Register elite_live_sk_ prefix with your VCS provider's secret scanning before onboarding.

Data Deletion (GDPR / Right to Erasure)#

Remove a student's mapping:

DELETE /api/v1/partners/students/{partner_student_ref}
X-Elite-Api-Key: elite_live_sk_xxx

For full account deletion (including Feynman transcripts, scores): email privacy@pankh.ai — processed within 30 days.

14. Changelog#

Backwards-compatible by default. Breaking changes are called out explicitly under each version with a migration note. If a version isn't listed, no partner-visible API changed.

v4.1 — 2026-05-04#

• Voice profile catalogue expanded from 5 → 19. Generic profiles still work unchanged (neutral, warm_female, warm_male, authoritative, energetic). 14 new persona-named profiles: Indian-English (priya, ananya, kavya, aarav, ritesh, kunal, rehaan) and US-English (ava, andrew, emma, brian, jenny, ryan, jack). See §5.4 Voice profile registry.
• HD voice upgrade for warm_female / warm_male. They now back onto Azure HD multilingual voices (Ava / Andrew Multilingual) instead of the older Aria / Guy. Audibly less synthetic. Existing partners get the upgrade automatically — no config change.
• SSML xml:lang auto-derives from voice locale. en-IN-* voices now get xml:lang='en-IN'; en-US-* voices get xml:lang='en-US'. Previously hardcoded to en-US, which forced Indian-English personas through US phoneme selection.
• system_prompt and partner blocks now honoured for moot_court and roleplay. Previously these were silently dropped for those two scenario types — the partner block renderer was only wired into feynman and mock_interview. Now consistent across all four scenario_type values.

Migration note: none required. Drop-in upgrade.

v4.0 — 2026-04-24#

• Partner prompt customisation. interview_config now accepts five bounded fields: user_background, learning_goal, topic_focus[], partner_context, and free-form system_prompt. All five are injection-scanned at mint time and rendered in labelled blocks below the identity block but above platform rules.
• voice_profile enum (initial). Choose from neutral, warm_female, warm_male, authoritative, energetic. Resolves server-side to the right Azure Neural voice and gpt-4o-realtime voice. (Expanded to 19 in v4.1.)
• Speech-safe TTS. /voice/synthesize normalises text server-side before synthesis — markdown markers, LaTeX delimiters, URLs, emojis, tables, footnotes, and code fences no longer leak into the spoken output.
• GET /api/v1/voice/profiles. New endpoint that lists the voice profile catalogue so your UI can render a picker without duplicating the map.
• Realtime voice fix. systemPrompt on POST /api/v1/voice/sessions now actually reaches Azure. Previously it was silently echoed in the response without being applied.
• Prompt-injection 422. Partner free-text fields containing blocked patterns return 422 VALIDATION_ERROR with context.field naming the offending field — the JWT is never minted. See §12.7.
• Session payload voice_profile. POST /feynman/sessions response now includes the resolved voice_profile so the browser can pick the correct voice without duplicating the map.

v3.0#

• Integration URLs in mint response. POST /partners/sessions now returns feynman_start_url, feynman_exchange_url, feynman_evaluate_url, voice_ws_url, pankh_base_url, plus an elite_session_id alias. No more URL concatenation on the partner side.
• interview_config at mint time. Pre-tag the interview's topic, difficulty, job description, company, and max exchanges in the JWT instead of repeating on every /feynman/sessions call.
• GET /partners/students/{ref}/sessions — list a student's interview sessions.
• GET /partners/students/{ref}/sessions/{session_id} — retrieve the full report (transcript + scorecard + instructor notes), gated until the instructor publishes.
• PATCH /partners/sessions/{session_id}/review — instructor review workflow (publish / flag).
• Self-serve key minting for allowlisted emails: GET /partners/self-serve/me, POST /partners/self-serve/keys.
• Admin email allowlist management: GET/POST/DELETE /partners/admin/self-serve-allowlist.
• PRO subscription bypass. Partner students no longer hit the consumer-tier gate on /voice/*, /feynman/*, /courses/*, etc. — partner orgs pay, individual students don't need Elite accounts.
• 422 hardening. Integration mistakes now return clean structured errors instead of opaque 500s.
• New sections: §6 Student Data Plane, §7 Review Workflow, §12 Troubleshooting.

Quick Reference#

Questions? partnerships@pankh.ai