API Reference

Base URL

http://localhost:4000/api/v1

Authentication

All endpoints require the x-api-key header:

x-api-key: sk_your_api_key

Endpoints

POST /exercises/evaluate

Evaluate a user’s answer to an exercise.

Headers:

Header	Required	Description
x-api-key	Yes	Your API key
Content-Type	Yes	application/json

Body:

Field	Type	Required	Description
exerciseId	string	Yes	Exercise identifier
area	string	Yes	Area: listening, reading, writing, vocabulary, grammar
type	string	Yes	Type: multiple_choice, fill_blank, open_answer
answer	string	Yes	User’s answer
correctAnswer	string	No	Correct answer for comparison
difficulty	number	No	Difficulty level (1-5)

Example:

{
  "exerciseId": "ex_001",
  "area": "listening",
  "type": "multiple_choice",
  "answer": "B",
  "correctAnswer": "B",
  "difficulty": 2
}

Response 201:

{
  "correct": true,
  "score": 10,
  "feedback": "Correct!",
  "metadata": {
    "area": "listening",
    "type": "multiple_choice"
  }
}

Response 401:

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

POST /admin/keys

Generate a new API key.

Body:

Field	Type	Required	Description
name	string	Yes	Descriptive name for the key

Example:

{
  "name": "my-app-frontend"
}

Response 201:

{
  "key": "sk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2",
  "message": "Save this key securely. It will not be shown again."
}

GET /admin/keys

List all registered API keys (without showing full keys).

Response 200:

[
  {
    "keyPreview": "sk_a1b2c...xyz9",
    "name": "Default (from .env)",
    "createdAt": "2026-05-04T13:00:00.000Z",
    "lastUsedAt": "2026-05-04T13:05:00.000Z",
    "isActive": true
  }
]

DELETE /admin/keys/:keyHash

Revoke an API key.

Path params:

Param	Type	Description
keyHash	string	SHA-256 hash of the key

Response 200:

{
  "revoked": true
}

Status Codes

Code	Meaning
200	Success
201	Resource created
400	Bad Request (validation failed)
401	Unauthorized (invalid or missing API key)
404	Not Found
500	Internal Server Error