Authentication & Rate Limiting

Base URL

http://localhost:4000/api/v1       # development
https://your-domain.com/api/v1    # production

Authentication

All endpoints except GET /health require the header:

x-api-key: sk_your_api_key

Missing or invalid key:

{
  "message": "Invalid or missing API key",
  "error": "Unauthorized",
  "statusCode": 401
}

Rate Limiting

Scope	Limit	Window
All endpoints	120 requests	60 seconds
/admin/*	10 requests	60 seconds

Returns HTTP 429 when exceeded.

Validation

The DTO uses forbidNonWhitelisted: true. Unknown fields are rejected:

{
  "message": ["property unknownField should not exist"],
  "error": "Bad Request",
  "statusCode": 400
}

Status Codes

Code	Meaning
200	Success
201	Created / evaluation completed
400	Bad Request - validation failed or required field missing
401	Unauthorized - invalid or missing API key
429	Too Many Requests - rate limit exceeded
500	Internal Server Error

Recommended STT Integration

The engine does not perform Speech-to-Text. For the Listening exercise, run your own STT pipeline (any provider of your choice) to transcribe the audio before calling this API, then submit the result:

{
  "type": "listening_multiple_choice",
  "content": {
    "audioUrl": "https://cdn.example.com/audio/lesson-12.mp3",
    "transcript": "John lives in London and works as a teacher.",
    "questions": [ "..." ]
  }
}

See Listening for the full content shape.