Developer Reference
REST API for AI-powered resume scoring and interview question generation. Built for ATS integrations — add contextual candidate intelligence to your hiring workflow in minutes.
sk-sw-demo-stackwright2025 to test
the API immediately — no account required. 100 requests/day on the demo key.
Jump to interactive demo →
Base URL
https://stackwright.polsia.app
What you can do
| Endpoint | What it does | Status |
|---|---|---|
| POST /api/v1/score-resume | Score a candidate's resume against a job description. Returns a fit score (0–100), strengths, gaps, and skill matches. | Live |
| POST /api/v1/generate-questions | Generate tailored interview questions from a JD (+ optional resume). Returns structured questions with evaluation criteria and follow-ups. | Soon |
Authentication
All API requests require an API key passed as a request header.
X-API-Key: sk-sw-your-api-key-here
Keys are prefixed with sk-sw-. Keep them secret — do not expose them in frontend code or commit them to version control.
sk-sw-demo-stackwright2025 — use this for testing. Rate limited to 100 requests/day. Not for production use.
Auth errors
| Status | Error code | Cause |
|---|---|---|
| 401 | MISSING_API_KEY | No X-API-Key header was sent. |
| 401 | INVALID_API_KEY | Key not found or revoked. |
Rate Limits
Limits are applied per API key, per day (resets at midnight UTC).
Rate limit headers
Every response includes these headers so you can track usage:
X-RateLimit-Limit: 10 # daily limit for your tier X-RateLimit-Remaining: 7 # requests left today X-RateLimit-Reset: 2025-03-18T00:00:00.000Z # next reset
resets_at timestamp. Back off until then.
Errors
All errors return JSON with a consistent structure:
{
"success": false,
"error": "ERROR_CODE",
"message": "Human-readable description"
}
| Status | Error code | Meaning |
|---|---|---|
| 400 | INVALID_INPUT | Missing or malformed request body field. Check the message for details. |
| 401 | MISSING_API_KEY | No X-API-Key header. |
| 401 | INVALID_API_KEY | Key not found or revoked. |
| 429 | RATE_LIMIT_EXCEEDED | Daily limit hit. Response includes used, limit, and resets_at. |
| 502 | AI_ERROR | Upstream AI model error. Retry with exponential backoff. |
Quick Start
Score your first resume in under 2 minutes. No account needed — use the demo key.
curl -X POST https://stackwright.polsia.app/api/v1/score-resume \ -H "X-API-Key: sk-sw-demo-stackwright2025" \ -H "Content-Type: application/json" \ -d '{ "resume_text": "Software Engineer with 5 years experience in Python and distributed systems. Led backend migration at Stripe. Built high-throughput data pipelines processing 10M events/day.", "job_description": "Senior Backend Engineer. Requirements: 4+ years Python, distributed systems experience, PostgreSQL. Nice to have: Kafka, Redis." }'
Get an API Key
The demo key works now, but for production use you'll need your own key with a higher rate limit.
- Join the waitlist at stackwright.polsia.app
- We'll email your API key within 24 hours
- Free tier includes 10 requests/day — upgrade to pro for unlimited
POST /api/v1/score-resume
Scores a candidate's resume against a job description using contextual AI analysis. Returns a fit score (0–100), identified strengths, gaps, skill matches, and a hiring recommendation.
Results are cached — identical resume + JD pairs return instantly without consuming your rate limit budget.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| resume_text | string | required | Candidate's resume as plain text. Min 50 chars, max 8,000 chars. Paste the full resume — structured sections preferred. |
| job_description | string | required | The job description as plain text. Min 30 chars, max 4,000 chars. Include requirements, responsibilities, and nice-to-haves for best results. |
Request example
{
"resume_text": "Jane Doe — Senior Software Engineer\n\nExperience:\n• Stripe (2021–2024) — Led migration of payment processing service from monolith to microservices. Reduced p99 latency by 40%.\n• Airbnb (2018–2021) — Backend engineer on Payments team. Built real-time fraud detection pipeline processing 2M events/day using Kafka + Python.\n\nSkills: Python, Go, PostgreSQL, Kafka, Redis, Kubernetes, AWS\n\nEducation: BS Computer Science, Stanford 2018",
"job_description": "Senior Backend Engineer — Payments Platform\n\nWe're looking for a senior engineer to lead backend development on our payments infrastructure.\n\nRequired:\n• 5+ years backend engineering experience\n• Python or Go proficiency\n• Experience with high-throughput distributed systems\n• PostgreSQL and Redis\n\nNice to have: Kafka, Kubernetes, prior fintech experience"
}
Response
| Field | Type | Description |
|---|---|---|
| success | boolean | true on success. |
| cached | boolean | true if result was served from cache (same resume+JD pair analyzed before). |
| fit_score | integer | Overall candidate fit, 0–100. 85+ = strong hire, 70–84 = worth interviewing, 55–69 = partial fit, below 55 = weak/poor fit. |
| strengths | string[] | 2–4 specific strengths this candidate brings to the role. |
| gaps | string[] | Identified gaps or missing requirements. |
| skill_matches | object[] | Array of {skill, level, evidence}. Level is one of strong, partial, or missing. Evidence cites specific resume content. |
| experience_alignment | string | 2–3 sentence analysis of career trajectory and seniority fit. |
| overall_assessment | string | Executive summary with a hiring recommendation. |
| processing_time_ms | integer | Wall time for this request in milliseconds. |
Response example
{
"success": true,
"cached": false,
"fit_score": 91,
"strengths": [
"Led microservices migration at Stripe — directly relevant to the payments platform work",
"Built high-throughput fraud detection pipeline at Airbnb using Kafka + Python — exact stack match",
"5+ years senior backend experience in fintech environments"
],
"gaps": [
"No explicit mention of direct team leadership or mentorship"
],
"skill_matches": [
{ "skill": "Python", "level": "strong", "evidence": "Listed in skills; used in fraud detection pipeline at Airbnb" },
{ "skill": "PostgreSQL", "level": "strong", "evidence": "Listed in skills section" },
{ "skill": "Kafka", "level": "strong", "evidence": "Kafka used in Airbnb fraud detection pipeline (2M events/day)" },
{ "skill": "Redis", "level": "strong", "evidence": "Listed in skills section" },
{ "skill": "Kubernetes", "level": "partial", "evidence": "Listed in skills but no specific project evidence" }
],
"experience_alignment": "Jane has exactly the experience profile this role requires: senior-level, payments domain, high-throughput systems. Her trajectory from Airbnb Payments to Stripe microservices work mirrors the challenge described in the JD.",
"overall_assessment": "Strong hire recommendation. Jane's background is an exceptionally precise match — fintech experience, correct stack, demonstrated impact at scale. The only open question is leadership scope, worth probing in the interview.",
"processing_time_ms": 1847
}
POST /api/v1/generate-questions
What it will do
Given a job description and (optionally) a candidate's resume, generate structured interview questions calibrated to the role's seniority and required skills. Questions include evaluation criteria and suggested follow-ups.
Request body (planned)
| Field | Type | Required | Description |
|---|---|---|---|
| job_description | string | required | The job description. Min 30 chars, max 4,000 chars. |
| resume | string | optional | Candidate resume to personalize questions — probe their specific gaps or validate claimed experience. Min 20 chars if provided. |
| num_questions | integer | optional | Number of questions to generate. Range: 1–20. Default: 5. |
| question_types | string[] | optional | Types to include. One or more of: technical, behavioral, system_design. Default: all three. |
Response shape (planned)
{
"success": true,
"cached": false,
"questions": [
{
"question": "Walk me through how you'd design a payment retry system that handles idempotency across distributed services.",
"type": "system_design",
"difficulty": "senior",
"evaluation_criteria": "Look for: idempotency keys, at-least-once delivery, dead letter queues, and explicit mention of failure modes.",
"follow_ups": [
"How would you handle the case where the payment processor returns a timeout but the charge went through?",
"What's your strategy for reconciliation if a retry creates a duplicate charge downstream?"
]
}
],
"job_context": {
"key_skills_extracted": ["Python", "distributed systems", "Kafka"],
"seniority_level": "senior",
"role_type": "backend"
},
"processing_time_ms": 2103
}
Try It
Run a live request against the API directly from this page. No signup required.
POST /api/v1/score-resume
sk-sw-demo-stackwright2025
// Response will appear here
Pricing
Simple, usage-based pricing. Start free, upgrade when you're ready to scale.
- 10 assessments / day
- Resume scoring API
- Demo API key (
sk-sw-demo-*) - JSON response + skill breakdown
- Question generation (coming soon)
- ATS integrations
- Webhook notifications
- 1,000 API calls/day
- Everything in Free
- Batch scoring (up to 50/request)
- Webhook callbacks
- Priority support (reply within 4h)
- 99.9% uptime SLA
- ATS integration guidance