Referencia de API

URL Base

http://localhost:4000/api/v1

Autenticación

Todos los endpoints requieren el header x-api-key:

x-api-key: sk_your_api_key

Endpoints

POST /exercises/evaluate

Evalúa la respuesta de un usuario a un ejercicio.

Headers:

Header	Requerido	Descripción
x-api-key	Sí	Tu API key
Content-Type	Sí	application/json

Body:

Campo	Tipo	Requerido	Descripción
exerciseId	string	Sí	Identificador del ejercicio
area	string	Sí	Área: listening, reading, writing, vocabulary, grammar
type	string	Sí	Tipo: multiple_choice, fill_blank, open_answer
answer	string	Sí	Respuesta del usuario
correctAnswer	string	No	Respuesta correcta para comparación
difficulty	number	No	Nivel de dificultad (1-5)

Ejemplo:

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

Respuesta 201:

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

Respuesta 401:

{
  "statusCode": 401,
  "message": "API key inválida o faltante",
  "error": "Unauthorized"
}

POST /admin/keys

Genera una nueva API key.

Body:

Campo	Tipo	Requerido	Descripción
name	string	Sí	Nombre descriptivo para la key

Ejemplo:

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

Respuesta 201:

{
  "key": "sk_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2",
  "message": "Guarda esta key de forma segura. No se mostrará de nuevo."
}

GET /admin/keys

Lista todas las API keys registradas (sin mostrar las keys completas).

Respuesta 200:

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

DELETE /admin/keys/:keyHash

Revoca una API key.

Path params:

Param	Tipo	Descripción
keyHash	string	Hash SHA-256 de la key

Respuesta 200:

{
  "revoked": true
}

Códigos de Estado

Código	Significado
200	Éxito
201	Recurso creado
400	Bad Request (validación fallida)
401	Unauthorized (API key inválida o faltante)
404	Not Found
500	Internal Server Error