Developer API Reference

// Successful response — resource returned directly (no wrapper)
{
  "id": "d290f1ee-...",
  "title": "Senior Backend Engineer Screen",
  "slug": "senior-backend-screen",
  ...
}

// Error response — always an error object
{
  "error": {
    "message": "Invalid API key.",
    "code": "INVALID_API_KEY"
  }
}

HTTP/1.1 429 Too Many Requests
Retry-After: 14

{
  "error": {
    "message": "Request was throttled. Expected available in 14 seconds.",
    "code": "RATE_LIMITED"
  }
}

// 403 response when quota is exceeded
{
  "error": {
    "message": "Monthly invite quota exceeded. Upgrade your plan to invite more candidates.",
    "code": "INVITE_QUOTA_EXCEEDED"
  }
}

// 400 response when assessment is not active
{
  "error": {
    "message": "This assessment is not active and cannot accept new invitations.",
    "code": "ASSESSMENT_NOT_ACTIVE"
  }
}

GET /api/v1/public/assessments/?status=active&search=backend
Authorization: Bearer ct_live_xxxxxxxxxxxxxxxx

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "title": "Senior Backend Engineer Screen",
      "slug": "senior-backend-screen",
      "status": "active",
      "case_count": 3,
      "time_limit_minutes": 90,
      "passing_score": 70,
      "invitation_count": 12,
      "enforce_fullscreen": true,
      "copy_paste_disabled": false
    }
  ],
  "meta": {
    "plan": "starter",
    "invite_limit": 100,
    "invites_used": 12,
    "invites_remaining": 88
  }
}

GET /api/v1/public/assessments/senior-backend-screen/
Authorization: Bearer ct_live_xxxxxxxxxxxxxxxx

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "slug": "senior-backend-screen",
  "title": "Senior Backend Engineer Screen",
  "description": "A 3-case technical screen covering SQL, Python, and system design.",
  "status": "active",
  "time_limit_minutes": 90,
  "passing_score": 70,
  "case_count": 3,
  "enforce_fullscreen": true,
  "copy_paste_disabled": false,
  "created_at": "2024-03-22T12:00:00Z"
}

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "c1...",
      "title": "SQL Join Master",
      "type": "platform",
      "case_type": "sql",
      "difficulty": "medium",
      "order": 0,
      "points": 100
    }
  ]
}

POST /api/v1/public/assessments/senior-backend-screen/invites/
Authorization: Bearer ct_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "email": "jane.doe@example.com",
  "name": "Jane Doe",
  "role": "Senior Backend Engineer",
  "send_email": true
}

{
  "message": "Invitation created successfully.",
  "invite_token": "c7b3e2a1-1234-5678-abcd-ef0123456789",
  "invite_url": "https://praxicraft.com/take/c7b3e2a1-1234-5678-abcd-ef0123456789",
  "expires_at": "2025-03-22T10:00:00Z",
  "status": "pending"
}

POST /api/v1/public/assessments/senior-backend-screen/invites/bulk/
Authorization: Bearer ct_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "candidates": [
    { "email": "alice@example.com", "name": "Alice Chen", "role": "Senior Backend Engineer" },
    { "email": "bob@example.com",   "name": "Bob Smith",  "role": "Senior Backend Engineer" },
    { "email": "jane@example.com"  }
  ],
  "send_email": true
}

{
  "invited": [
    {
      "email": "alice@example.com",
      "invite_token": "a1b2c3d4-...",
      "invite_url": "https://praxicraft.com/take/a1b2c3d4-..."
    },
    {
      "email": "bob@example.com",
      "invite_token": "e5f6a7b8-...",
      "invite_url": "https://praxicraft.com/take/e5f6a7b8-..."
    }
  ],
  "skipped": [
    { "email": "jane@example.com", "reason": "already invited" }
  ]
}

GET /api/v1/public/invites/c7b3e2a1-.../
Authorization: Bearer ct_live_xxxxxxxxxxxxxxxx

{
  "invite_token": "c7b3e2a1-1234-5678-abcd-ef0123456789",
  "email": "jane.doe@example.com",
  "name": "Jane Doe",
  "role": "Senior Backend Engineer",
  "status": "started",
  "assessment": {
    "slug": "senior-backend-screen",
    "title": "Senior Backend Engineer Screen"
  },
  "created_at": "2025-03-15T09:00:00Z",
  "expires_at": "2025-03-22T09:00:00Z",
  "started_at": "2025-03-15T14:00:00Z",
  "completed_at": null,
  "reminded_at": null
}

POST /api/v1/public/invites/c7b3e2a1-.../remind/
Authorization: Bearer ct_live_xxxxxxxxxxxxxxxx

{
  "message": "Reminder sent."
}

DELETE /api/v1/public/invites/c7b3e2a1-.../
Authorization: Bearer ct_live_xxxxxxxxxxxxxxxx

HTTP/1.1 204 No Content

GET /api/v1/public/invites/
Authorization: Bearer ct_live_xxxxxxxxxxxxxxxx

{
  "count": 125,
  "next": "http.../public/invites/?page=2",
  "previous": null,
  "results": [
    {
      "invite_token": "c7b3e2a1-...",
      "assessment_title": "Senior Backend Engineer Screen",
      "assessment_slug": "senior-backend-screen",
      "email": "jane@example.com",
      "status": "completed",
      "sent_at": "2025-03-15T14:00:00Z"
    }
  ]
}

GET /api/v1/public/assessments/senior-backend-screen/results/
Authorization: Bearer ct_live_xxxxxxxxxxxxxxxx

{
  "count": 2,
  "results": [
    {
      "candidate_email": "jane@example.com",
      "candidate_name": "Jane Doe",
      "status": "completed",
      "score_percentage": 85.0,
      "passed": true,
      "started_at": "2025-03-15T14:00:00Z",
      "completed_at": "2025-03-15T15:20:00Z",
      "invite_token": "c7b3e2a1-..."
    }
  ]
}

GET /api/v1/public/invites/c7b3e2a1-.../result/
Authorization: Bearer ct_live_xxxxxxxxxxxxxxxx

{
  "candidate_email": "jane@example.com",
  "candidate_name": "Jane Doe",
  "assessment": "Senior Backend Engineer Screen",
  "status": "completed",
  "score": 255,
  "max_score": 300,
  "score_percentage": 85.0,
  "passed": true,
  "passing_score": 70,
  "started_at": "2025-03-15T14:00:00Z",
  "completed_at": "2025-03-15T15:20:00Z",
  "violation_counts": {
    "fullscreen_violations": 0,
    "copy_paste_violations": 2
  },
  "detailed_report_url": "/api/v1/assess/assessments/senior-backend-screen/results/...",
  "cases": [
    {
      "case_order": 1,
      "case_title": "Query Optimization",
      "score": 100,
      "max_score": 100,
      "status": "correct",
      "time_spent_seconds": 820
    },
    {
      "case_order": 2,
      "case_title": "ETL Pipeline",
      "score": 100,
      "max_score": 100,
      "status": "correct",
      "time_spent_seconds": 1540
    },
    {
      "case_order": 3,
      "case_title": "Data Modeling",
      "score": 55,
      "max_score": 100,
      "status": "incorrect",
      "time_spent_seconds": 2100
    }
  ]
}

{
  "count": 42,
  "results": [
    {
      "id": "e21a...",
      "title": "Custom Algorithm 1",
      "case_type": "coding",
      "difficulty": "hard"
    }
  ]
}

{
  "id": "new-uuid",
  "title": "My New Case"
}

{
  "id": "e21a...",
  "title": "Custom Algorithm 1",
  "question": "### Implement Quicksort...",
  "case_type": "coding"
}

{
  "id": "e21a...",
  "title": "Updated Title"
}

HTTP/1.1 204 No Content

{
  "count": 2,
  "results": [
    {
      "id": "p1...",
      "title": "Grad Program 2025",
      "slug": "grad-2025",
      "stage_count": 3
    }
  ]
}

{
  "id": "p1...",
  "title": "Grad Program 2025",
  "stages": [
    { "order": 0, "assessment_title": "Initial Screen", "assessment_slug": "initial-screen" },
    { "order": 1, "assessment_title": "Technical Deep Dive", "assessment_slug": "tech-deep-dive" }
  ]
}

{
  "message": "Candidate enrolled successfully.",
  "enrollment_id": "e1...",
  "status": "active",
  "current_stage": 0
}

{
  "id": "e1...",
  "status": "active",
  "current_stage": 1,
  "history": [
    { "event": "enrolled", "timestamp": "..." },
    { "event": "stage_completed", "stage": 0, "score": 95 }
  ]
}

{
  "count": 1,
  "results": [
    {
      "id": "550e8400-...",
      "url": "https://api.acme.com/webhooks",
      "is_active": true,
      "event_types": ["assessment.completed", "candidate.passed"]
    }
  ]
}

{
  "id": "550e8400-...",
  "signing_secret": "whsec_..."
}

{
  "message": "Test succeeded — endpoint responded with 200.",
  "status_code": 200,
  "is_verified": true
}

// Python verification example
import hmac, hashlib

def verify(secret: str, raw_body: bytes, header_sig: str) -> bool:
    expected = hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header_sig)

// candidate.passed payload
{
  "event": "candidate.passed",
  "created_at": "2025-03-15T15:21:00Z",
  "data": {
    "session_id": "e1f2a3b4-...",
    "assessment_id": "d290f1ee-...",
    "assessment_slug": "senior-backend-screen",
    "candidate_email": "jane@example.com",
    "candidate_name": "Jane Doe",
    "score": 255,
    "max_score": 300,
    "passed": true
  }
}

// 401 — Missing or invalid API key
{
  "error": {
    "message": "Invalid API key.",
    "code": "INVALID_API_KEY"
  }
}

// 400 — Validation error
{
  "error": {
    "message": "email is required",
    "code": "MISSING_EMAIL"
  }
}

// 404 — Resource not found
{
  "error": {
    "message": "Assessment not found.",
    "code": "NOT_FOUND"
  }
}

// 403 — Invite quota exceeded
{
  "error": {
    "message": "Monthly invite quota exceeded. Upgrade your plan to invite more candidates.",
    "code": "INVITE_QUOTA_EXCEEDED"
  }
}

// 400 — Assessment not in active status
{
  "error": {
    "message": "This assessment is not active and cannot accept new invitations.",
    "code": "ASSESSMENT_NOT_ACTIVE"
  }
}

// 429 — Rate limited
{
  "error": {
    "message": "Request was throttled. Expected available in 8 seconds."
  }
}

GET /api/v1/public/org/
Authorization: Bearer ct_live_xxxxxxxxxxxxxxxx

{
  "name": "Acme Corp",
  "slug": "acme-corp",
  "plan": "starter",
  "invite_limit": 100,
  "invites_used": 23,
  "invites_remaining": 77
}

GET /api/v1/public/org/team/
Authorization: Bearer ct_live_xxxxxxxxxxxxxxxx

{
  "count": 3,
  "results": [
    { "name": "Sarah Chen",  "email": "sarah@acme.com",  "role": "owner" },
    { "name": "James Okafor","email": "james@acme.com",  "role": "admin" },
    { "name": "Priya Nair",  "email": "priya@acme.com",  "role": "recruiter" }
  ]
}

GET /api/v1/public/org/stats/
Authorization: Bearer ct_live_xxxxxxxxxxxxxxxx

{
  "total_invites": 450,
  "total_candidates": 380,
  "completed_assessments": 365,
  "passed_candidates": 210,
  "pass_rate": 57.5,
  "average_score_percentage": 68.2,
  "active_assessments": 12
}