docs/api.md

API And Product Behavior

Auth Model

• If REQUIRE_AUTH=true, analysis endpoints require Hugging Face sign-in.
• Sessions are scoped to user identity.
• One user cannot fetch another user’s session or export.

Session Model

Statuses:

• queued
• generating
• answer_ready
• analyzing
• completed
• failed

Sessions are ephemeral for current running instance.

Endpoints

GET /healthz

Returns:

• model name
• device preference
• dtype preference
• auth requirement
• queue limits
• CUDA / MPS availability

GET /api/me

Returns current auth state plus login/logout URLs.

POST /api/warmup

Loads model with current runtime policy and returns:

• resolved device
• resolved dtype
• model attribution capability

POST /api/analyze

Direct synchronous analysis call. Good for trusted programmatic use, not best path for UI.

GET /api/sessions

List current user’s recent sessions on current instance.

POST /api/sessions

Create async session job.

Queue protections:

• global queue cap
• per-user active-job cap

GET /api/sessions/{id}

Return session summary.

GET /api/sessions/{id}/result

Return session summary + full analysis if ready.

Export

• GET /api/sessions/{id}/export.json
• GET /api/sessions/{id}/export.csv

JSON contains session + analysis payload.

CSV contains top edges:

• source_sentence_idx
• target_sentence_idx
• score