API Reference

List jobs in your company. Supports pagination via limit and offset.

Request

curl https://screenly.qubith.in/api/v1/jobs?limit=50&offset=0 \
  -H "Authorization: Bearer sk_live_…"

Response

{
  "jobs": [
    { "id": 42, "title": "Senior Frontend Engineer",
      "description": "5+ years React, TypeScript…",
      "status": "active", "created_at": "2026-09-29T…" }
  ],
  "total": 7, "limit": 50, "offset": 0
}

Get a single job with its top 200 ranked candidates.

Request

curl https://screenly.qubith.in/api/v1/jobs/42 \
  -H "Authorization: Bearer sk_live_…"

Response

{
  "job": { "id": 42, "title": "…", "description": "…", "status": "active" },
  "candidates": [
    { "id": 1001, "candidate_name": "Priya Sharma",
      "overall_score": 92, "fit_classification": "STRONG_FIT" }
  ]
}

Create a new job. Description is the JD text the ranker uses (min 20 chars).

Request

curl -X POST https://screenly.qubith.in/api/v1/jobs \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Senior Frontend Engineer",
    "description": "5+ years React. TypeScript. Ship to production. …"
  }'

Response

{
  "ok": true,
  "id": 43,
  "job": { "id": 43, "title": "Senior Frontend Engineer",
           "description": "5+ years React…", "status": "active" }
}

Update a job. Any of title, description, or status (active | archived).

Request

curl -X PATCH https://screenly.qubith.in/api/v1/jobs/43 \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Staff Frontend Engineer", "status": "archived" }'

Response

{ "ok": true, "id": 43 }

Soft-archive a job (status='deleted'). Candidates and history are preserved.

Request

curl -X DELETE https://screenly.qubith.in/api/v1/jobs/43 \
  -H "Authorization: Bearer sk_live_…"

Response

{ "ok": true, "id": 43, "status": "deleted" }

Upload one or more resume files (multipart, field name: files). PDF or text. Up to 5 MB per file, 50 files per request. Scoring runs asynchronously — poll the returned candidate IDs.

Request

curl -X POST https://screenly.qubith.in/api/v1/jobs/42/resumes \
  -H "Authorization: Bearer sk_live_…" \
  -F "files=@priya_sharma.pdf" \
  -F "files=@arjun_patel.pdf" \
  -F "files=@neha_verma.txt"

Response

{
  "ok": true,
  "job_id": 42,
  "batch_id": 8812,
  "uploaded": 3,
  "failed": 0,
  "resume_ids": [12001, 12002, 12003],
  "errors": []
}

Get a 1-hour presigned URL to download the original resume file.

Request

curl https://screenly.qubith.in/api/v1/candidates/12001/download \
  -H "Authorization: Bearer sk_live_…"

Response

{
  "url": "https://tigris.example/screenly/…?X-Amz-Signature=…",
  "expires_in": 3600,
  "filename": "priya_sharma.pdf"
}

List ranked candidates for a job. Filter by min_score, status (new|shortlisted|rejected|interview|hired), or free-text q on name/email. Paginated.

Request

curl "https://screenly.qubith.in/api/v1/jobs/42/candidates?min_score=70&status=shortlisted&limit=50" \
  -H "Authorization: Bearer sk_live_…"

Response

{
  "job_id": 42,
  "candidates": [
    { "id": 12001, "candidate_name": "Priya Sharma",
      "email": "priya@example.com", "phone": "+91-9876543210",
      "overall_score": 92, "fit_classification": "STRONG_FIT",
      "skills_score": 95, "experience_score": 90,
      "education_score": 88, "location_score": 92,
      "red_flags": false, "recruiter_status": "shortlisted",
      "processed_at": "2026-09-29T17:43:12.000Z",
      "created_at": "2026-09-29T17:42:50.000Z" }
  ],
  "total": 14, "limit": 50, "offset": 0
}

Get one candidate's full record — scores, summary, strengths, gaps, notes.

Request

curl https://screenly.qubith.in/api/v1/candidates/12001 \
  -H "Authorization: Bearer sk_live_…"

Response

{
  "id": 12001, "job_id": 42, "candidate_name": "Priya Sharma",
  "email": "priya@example.com", "phone": "+91-9876543210",
  "overall_score": 92, "fit_classification": "STRONG_FIT",
  "fit_probability": 0.92,
  "skills_score": 95, "experience_score": 90,
  "education_score": 88, "location_score": 92,
  "red_flags": false,
  "summary_text": "Senior FE with 6 yrs of React + TS at consumer startups.",
  "strengths_json": ["Strong React/TS fundamentals", "Shipped 0-to-1 product"],
  "gaps_json": ["No prior fintech experience"],
  "recruiter_status": "shortlisted",
  "notes": "Phone screen passed. Take-home next.",
  "processed_at": "2026-09-29T17:43:12.000Z"
}

Update recruiter status (new|shortlisted|rejected|interview|hired) and/or notes (max 5000 chars).

Request

curl -X PATCH https://screenly.qubith.in/api/v1/candidates/12001 \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "status": "interview", "notes": "Round 2 scheduled Fri 4pm" }'

Response

{ "ok": true, "id": 12001 }

Re-score a candidate against the current JD. Useful after JD edits or to refresh stale scores. Async — poll the candidate record for the new score.

Request

curl -X POST https://screenly.qubith.in/api/v1/candidates/12001/evaluate \
  -H "Authorization: Bearer sk_live_…"

Response

{
  "ok": true, "id": 12001, "status": "pending",
  "message": "Resume re-queued for scoring. Poll GET /candidates/:id for status."
}

Permanently remove a candidate and their resume file from your tenant.

Request

curl -X DELETE https://screenly.qubith.in/api/v1/candidates/12001 \
  -H "Authorization: Bearer sk_live_…"

Response

{ "ok": true, "id": 12001 }