Developer Documentation

POST /api/v1/api-keys
Authorization: Bearer <session-token>

{
  "name": "Greenhouse Production",
  "scopes": ["interviews:read", "interviews:write", "candidates:write", "feedback:read"],
  "environment": "live"
}

// Response
{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "Greenhouse Production",
    "key_prefix": "mk_live_a1b2",
    "plaintext_key": "mk_live_a1b2c3d4...",   // ← shown only once
    "scopes": ["interviews:read", "interviews:write", ...],
    "environment": "live",
    "created_at": "2026-03-11T10:00:00Z",
    "warning": "Store this key securely. It will not be shown again."
  }
}

// Success response envelope
{
  "success": true,
  "data": { ... },
  "meta": {
    "request_id": "req_lf3k2_abc123",
    "timestamp": "2026-03-11T10:00:00Z"
  }
}

// Error response envelope
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": [{ "field": "email", "issue": "required" }]
  },
  "meta": { "request_id": "req_lf3k2_abc123" }
}

// evaluation.generated example
{
  "event": "evaluation.generated",
  "timestamp": "2026-03-11T11:36:12Z",
  "data": {
    "feedback_id": "7b2c4d...",
    "total_score": 82.5,
    "category_scores": [
      { "name": "Technical Knowledge", "score": 88 },
      { "name": "Problem Solving",     "score": 80 },
      { "name": "Communication",       "score": 79 }
    ]
  }
}

// interview.completed example
{
  "event": "interview.completed",
  "timestamp": "2026-03-11T11:35:00Z",
  "data": {
    "interview_id": "550e8400-...",
    "feedback_id": "7b2c4d...",
    "candidate_email": "candidate@company.com"
  }
}

// Node.js signature verification
import { createHmac } from "crypto";

function verifyWebhook(body, signature, timestamp, secret) {
  const data    = `${timestamp}.${body}`;
  const expected = createHmac("sha256", secret)
    .update(data)
    .digest("hex");
  return signature === expected;
}

// Express route handler
app.post("/webhooks/mukhtabir", express.raw({ type: "*/*" }), (req, res) => {
  const sig       = req.headers["x-mukhtabir-signature"];
  const timestamp = req.headers["x-mukhtabir-timestamp"];
  const secret    = process.env.MUKHTABIR_WEBHOOK_SECRET;

  if (!verifyWebhook(req.body.toString(), sig, timestamp, secret)) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(req.body);
  console.log("Event:", event.event, event.data);
  res.sendStatus(200);
});

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 94
X-RateLimit-Reset: 1741694460
X-Request-Id: req_lf3k2_abc123

// When limit is exceeded:
HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/json

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later."
  }
}

# Create an interview
curl -X POST https://mukhtabir.hbku.edu.qa/api/v1/interviews \
  -H "Authorization: Bearer mk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "Senior Software Engineer",
    "type": "technical",
    "level": "senior",
    "duration": 30,
    "techstack": ["Python", "Django", "PostgreSQL"],
    "max_score": 100,
    "visibility": "restricted"
  }'

# Invite a candidate
curl -X POST https://mukhtabir.hbku.edu.qa/api/v1/interviews/{id}/invite \
  -H "Authorization: Bearer mk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "candidate@company.com",
    "name": "Sarah Al-Rashid",
    "expires_in_hours": 72
  }'

# Retrieve evaluation results
curl -X GET https://mukhtabir.hbku.edu.qa/api/v1/feedback/{feedbackId} \
  -H "Authorization: Bearer mk_live_your_api_key_here"

# Python webhook verification with Flask
import hmac, hashlib, json
from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_your_secret_here"

@app.route("/webhooks/mukhtabir", methods=["POST"])
def handle_webhook():
    sig       = request.headers.get("X-Mukhtabir-Signature", "")
    timestamp = request.headers.get("X-Mukhtabir-Timestamp", "")
    body      = request.get_data(as_text=True)

    data     = f"{timestamp}.{body}"
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        data.encode(),
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(sig, expected):
        abort(401)

    event = json.loads(body)
    print(f"Event: {event['event']}")

    if event["event"] == "evaluation.generated":
        feedback_id = event["data"]["feedback_id"]
        score       = event["data"]["total_score"]
        print(f"Candidate scored {score}/100 — fetching full results...")
        # fetch_full_evaluation(feedback_id)

    return "", 200