docs/api.md

Talentry AI - HTTP API

The FastAPI server (talentry-serve or the HuggingFace Space deployment) exposes three endpoints. All payloads are JSON; the only non-JSON response is the CSV download.

Live URL: https://huggingface.co/spaces/williyam/talentry-ai Repo on HF: https://huggingface.co/spaces/williyam/talentry-ai Open-source fine-tuned LLM: https://huggingface.co/williyam/redrob-qwen-grpo

(the same origin serves the React SPA).

---

GET /api/health

Liveness probe.

{ "status": "ok", "version": "1.0.0" }

---

GET /api/sample?limit=10

Return up to limit candidate records from the default 50-row fixture (data/raw/sample_candidates.json). Useful for UI bootstrapping.

limit is clamped to [1, 100]. Returns an array of raw candidate dicts matching candidate_schema.json.

---

POST /api/rank?use_sample=false&top_k=10

Run the full ranking pipeline.

Multipart body:

Field	Required	Notes
candidates	yes unless use_sample=true	.json / .jsonl / .jsonl.gz upload
jd	no	.txt / .md; defaults to the default JD

Query parameters:

Name	Default	Notes
use_sample	false	If true, ignores candidates and uses the default fixture.
top_k	10	Clamped to [1, 100]. Validator-clean CSV only at top_k=100.

Response:

{
  "version": "1.0.0",
  "jd": {
    "title": "Senior AI Engineer",
    "seniority": "senior",
    "min_years": 5.0,
    "max_years": 9.0,
    "must_have_skills": [...],
    "preferred_locations": [...]
  },
  "n_candidates": 50,
  "n_returned": 10,
  "session_id": null,
  "results": [
    {
      "candidate_id": "CAND_0000031",
      "rank": 1,
      "score": 1.0101,
      "reasoning": "Strong match - Recommendation Systems Engineer ...",
      "breakdown": {
        "title_alignment": 0.9,
        "semantic_fit": 0.74,
        "skill_evidence": 0.81,
        "experience_band": 1.0,
        "location": 0.85,
        "behavioural": 1.18,
        "honeypot_penalty": 0.0,
        "final": 1.0101
      }
    }
  ]
}

When top_k=100 and the input has ≥ 100 candidates, a session_id is returned and the CSV is persisted for download.

---

GET /api/submission.csv?session=<id>

Download the validator-clean ranked shortlist produced by a prior /api/rank call. The file is delivered as Ranked_shortlist.csv in the browser; only top_k=100 results pass the official validate_submission.py validator.

Sessions are kept in process memory and will not survive a restart.

GET /api/submission.xlsx?session=<id>

Same shortlist as submission.csv but returned as a styled XLSX workbook (frozen header, sized columns, wrapped reasoning column). The file is delivered as Ranked_shortlist.xlsx.

---

CORS

The server allows all origins (*) so the UI and any external sandbox checker can call it freely.