Back to Resume Matcher

Backend API Requirements

docs/agent/apis/backend-requirements.md

1.2.02.1 KB
Original Source

Backend API Requirements

API contract specifications for Resume Matcher.

Base URL

http://localhost:8000/api/v1

Authentication

Currently none (local-first design).

Endpoints

Health & Status

GET /health           → {healthy, provider, model, error?}
GET /status           → {status, llm_configured, llm_healthy, database_stats}

Configuration

GET /config/llm-api-key    → {provider, model, api_key(masked), api_base?}
PUT /config/llm-api-key    ← {provider, model, api_key, api_base?}
POST /config/llm-test      → {healthy, provider, model}
GET /config/features       → {enable_cover_letter, enable_outreach_message}
PUT /config/features       ← {enable_cover_letter?, enable_outreach_message?}

Resumes

POST /resumes/upload       ← multipart/form-data {file}
                           → {resume_id}
GET /resumes?resume_id=    → Resume object
GET /resumes/list          → [{resume_id, filename, is_master, created_at}]
PATCH /resumes/{id}        ← {processed_data, cover_letter?, outreach_message?}
DELETE /resumes/{id}       → {message}
GET /resumes/{id}/pdf      → application/pdf
POST /resumes/improve      ← {resume_id, job_id}
                           → {data, cover_letter?, outreach_message?}

Jobs

POST /jobs/upload          ← {job_descriptions: [], resume_id?}
                           → {job_id: []}
GET /jobs/{id}             → {job_id, content, created_at}

Request/Response Formats

Resume Object

json
{
  "resume_id": "uuid",
  "content": "markdown or json",
  "processed_data": {
    "personalInfo": {...},
    "summary": "...",
    "workExperience": [...],
    "education": [...],
    "additional": {...}
  },
  "is_master": true,
  "processing_status": "ready|processing|failed",
  "cover_letter": "text or null",
  "outreach_message": "text or null"
}

Error Response

json
{
  "detail": "Error message"
}

Status Codes

CodeMeaning
400Bad request
404Not found
413File too large (>4MB)
422Parsing failed
500Server error
503PDF rendering failed