REST API

The ALOT API is a versioned REST API hosted at https://api.yourdomain.com/v1. All responses follow a consistent envelope format.

Base URL

https://api.yourdomain.com/v1

{
  "data": { ... },       // Payload
  "message": "...",      // Optional success message
  "timestamp": "2026-05-25T12:00:00.000Z"
}

Errors return:

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": ["email must be an email"],
  "timestamp": "...",
  "path": "/v1/auth/login"
}

List endpoints accept ?page=1&limit=20 and return:

{
  "data": {
    "items": [...],
    "total": 142,
    "page": 1,
    "limit": 20
  }
}

Method	Path	Description
POST	/auth/register	Register user + create org
POST	/auth/login	Login, returns access + refresh tokens
POST	/auth/refresh	Refresh access token
POST	/auth/logout	Invalidate refresh token
GET	/auth/me	Get current user + org

Method	Path	Description
GET	/assessments	List assessments (paginated)
POST	/assessments	Create assessment
GET	/assessments/:id	Get assessment with stages
PATCH	/assessments/:id	Update assessment
DELETE	/assessments/:id	Delete assessment
POST	/assessments/:id/publish	Publish assessment
POST	/assessments/:id/archive	Archive assessment
POST	/assessments/:id/duplicate	Clone assessment + stages
GET	/assessments/:id/stages	List stages
POST	/assessments/:id/stages	Add stage
PATCH	/assessments/:id/stages/:stageId	Update stage
DELETE	/assessments/:id/stages/:stageId	Delete stage
POST	/assessments/:id/reorder-stages	Reorder stages
POST	/assessments/generate-questions	AI question generation (PRO)

Method	Path	Description
GET	/candidates	List all candidate sessions
GET	/candidates/:id	Get candidate session
POST	/candidates/:assessmentId/invite	Invite candidate by email

Method	Path	Description
GET	/billing/subscription	Get current org subscription
POST	/billing/checkout	Create Paystack checkout session
POST	/billing/verify	Verify Paystack transaction by reference
POST	/billing/cancel	Cancel subscription
GET	/billing/manage	Get Paystack management URL
POST	/billing/webhook/paystack	Paystack webhook receiver (public)

Method	Path	Description
GET	/api-keys	List API keys (prefix only)
POST	/api-keys	Create API key (full key shown once)
DELETE	/api-keys/:id	Revoke API key

Method	Path	Description
GET	/analytics/dashboard	Dashboard stats
GET	/analytics/assessments/:id	Per-assessment analytics

Method	Path	Description
GET	/public/assessments	List published assessments
GET	/public/assessments/:id	Get assessment
GET	/public/assessments/:id/candidates	List candidates for assessment
GET	/public/candidates	List candidate sessions
GET	/public/candidates/:id	Get candidate session
GET	/public/results/:token	Get results by result token

The API enforces three tiers of rate limits:

Exceeding limits returns HTTP 429 Too Many Requests.