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.

Try before you sign up. Use the demo key 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

Base
https://stackwright.polsia.app

What you can do

EndpointWhat it doesStatus
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.

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.

🔑
Demo key: sk-sw-demo-stackwright2025 — use this for testing. Rate limited to 100 requests/day. Not for production use.

Auth errors

StatusError codeCause
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).

Free tier
10/day
Resets midnight UTC. Upgrade for more.
Pro tier
Unlimited
No daily cap. Fair use applies.

Rate limit headers

Every response includes these headers so you can track usage:

Response Headers
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
⚠️
When you hit the limit you'll get a 429 RATE_LIMIT_EXCEEDED response with a resets_at timestamp. Back off until then.

Errors

All errors return JSON with a consistent structure:

Error shape
{
  "success": false,
  "error":   "ERROR_CODE",
  "message": "Human-readable description"
}
StatusError codeMeaning
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
Terminal
🐍
Python
requests
JavaScript
fetch / Node
cURL
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.

  1. Join the waitlist at stackwright.polsia.app
  2. We'll email your API key within 24 hours
  3. Free tier includes 10 requests/day — upgrade to pro for unlimited
📬
Building something serious? Email us at stackwright@polsia.app and we'll get you set up with a pro key immediately.

POST /api/v1/score-resume

POST https://stackwright.polsia.app/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

FieldTypeRequiredDescription
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

JSON
{
  "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

FieldTypeDescription
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

JSON — 200 OK
{
  "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

POST https://stackwright.polsia.app/api/v1/generate-questions Coming Soon
🚧
This endpoint is in development. Generate tailored interview questions from a job description (with optional resume context). The API is designed and ready — we're finishing final testing. Get on the waitlist and we'll notify you when it's live.

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)

FieldTypeRequiredDescription
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)

JSON — 200 OK
{
  "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
Uses demo key · 100 req/day limit
Status Time
// Response will appear here

Pricing

Simple, usage-based pricing. Start free, upgrade when you're ready to scale.

Free
Starter
$0/mo
API key included. No credit card.
  • 10 assessments / day
  • Resume scoring API
  • Demo API key (sk-sw-demo-*)
  • JSON response + skill breakdown
  • Question generation (coming soon)
  • ATS integrations
  • Webhook notifications
Get free API key
💬
Need a custom plan or want to discuss volume pricing? Email stackwright@polsia.app — we respond same day.