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`