CV
CV Optimizer KE

API Documentation

CV Optimizer KE exposes a set of REST API endpoints for CV analysis, authentication, and M-Pesa payment processing.

Version 1.0REST APIJSON

Base URL

https://ai-powered-cv-optimizer.vercel.app/api

All endpoints are relative to this base URL. All requests and responses use JSON.

Authentication

All protected endpoints require an active Supabase session cookie. Authentication is handled via Supabase Auth — users must be signed in through the app before making API requests.

⚠️ Requests without a valid session will return 401 Unauthorized

Endpoints

POST/api/analyze🔒 Requires auth

Analyzes a CV against a job description using Groq AI (Llama 3.3 70B). Returns ATS score, match score, missing keywords, rewritten summary, and interview tips. First analysis is free. Subsequent analyses require payment.

Request body

{
  "cvBase64": "string",      // Base64-encoded PDF file (required)
  "jobDescription": "string", // Full job description text (required)
  "jobTitle": "string",      // Job title for history (optional)
  "paid": "boolean"          // true if user has paid (default: false)
}

Success response 200

{
  "result": {
    "ats_score": 84,
    "match_score": 91,
    "readability_score": 78,
    "missing_keywords": ["React.js", "Docker", "Agile"],
    "found_keywords": ["Python", "SQL", "Git"],
    "rewritten_summary": "Experienced software developer...",
    "weak_sections": "Work experience section lacks quantifiable achievements...",
    "interview_tips": "Prepare to discuss your Python projects..."
  }
}

Error responses

401Unauthorized— User is not logged in
400Bad Request— CV text could not be extracted from PDF
402Payment Required— Free analysis used, payment needed
500Server Error— AI analysis failed
POST/api/mpesa/initiate🔒 Requires auth

Initiates an M-Pesa STK Push payment request to the user's phone via Safaricom Daraja API. The user receives a payment prompt on their phone and enters their M-Pesa PIN to complete the transaction.

Request body

{
  "phone": "0712345678",  // Kenyan phone number (required)
  "amount": 200           // Amount in KES (required)
}

Success response 200

{
  "success": true,
  "data": {
    "MerchantRequestID": "29115-34620561-1",
    "CheckoutRequestID": "ws_CO_271012022...",
    "ResponseCode": "0",
    "ResponseDescription": "Success. Request accepted for processing",
    "CustomerMessage": "Success. Request accepted for processing"
  }
}

Error responses

401Unauthorized— User is not logged in
400Bad Request— Phone or amount missing
500Server Error— Safaricom API error
POST/api/mpesa/callback🌐 Public — Safaricom only

Webhook endpoint called by Safaricom after payment is completed or failed. Updates the payment status in the database and credits the user with a paid analysis. This endpoint is public and called automatically by Safaricom.

Safaricom payload

{
  "Body": {
    "stkCallback": {
      "ResultCode": 0,
      "ResultDesc": "The service request is processed successfully.",
      "CallbackMetadata": {
        "Item": [
          { "Name": "Amount", "Value": 200 },
          { "Name": "MpesaReceiptNumber", "Value": "NLJ7RT61SV" },
          { "Name": "PhoneNumber", "Value": 254712345678 }
        ]
      }
    }
  }
}

ℹ️ ResultCode 0 = success. Any other code = payment failed or cancelled.

GET/api/admin/stats🔒 Admin only

Returns platform-wide statistics including total users, analyses, payments, and revenue. Also returns recent users, analyses, and payments. Only accessible by users with is_admin = true.

Success response 200

{
  "stats": {
    "total_users": 42,
    "total_analyses": 128,
    "total_payments": 35,
    "total_revenue": 7000
  },
  "recentUsers": [...],
  "recentAnalyses": [...],
  "recentPayments": [...],
  "dailyAnalyses": [...]
}

Error responses

401Unauthorized— User is not logged in
403Forbidden— User is not an admin

Tech stack

FrameworkNext.js 15 (App Router)
LanguageTypeScript
AI ModelLlama 3.3 70B via Groq
DatabaseSupabase (PostgreSQL)
AuthSupabase Auth
PaymentsM-Pesa Daraja API
StylingTailwind CSS v4
HostingVercel
CI/CDGitHub Actions
TestingJest + ts-jest

CV Optimizer KE · Built in Kenya 🇰🇪 · 2026