Grades API — record and retrieve student scores

The Grades (Notas) API records individual student scores against specific evaluations. Any authenticated user can both read and write grade data through this endpoint. For role-scoped grade recording — where only the assigned teacher may post grades — use the /api/docente/notas endpoint instead. Base URL: /api/notas Auth: All endpoints require a Bearer token in the Authorization header.

Evaluacion vs. Nota — these are two distinct entities in PlataformaEduca’s grading model. An Evaluacion is the assessment itself: it defines a title, a percentage weight within the course, a date, and which course and teacher assignment it belongs to. A Nota is a student’s score on that assessment: it records the numeric grade and an optional teacher comment, linking one Evaluacion to one Estudiante. In short, one Evaluacion can have many Nota records — one per enrolled student.

GET /api/notas
POST /api/notas
GET /api/notas/estudiante/{id}

List all grades

Returns every Nota record in the system. No filtering is applied; use GET /api/notas/estudiante/{id} to scope results to a single student.

Response fields

integer

Unique grade record ID.

nota

number

The numeric score (e.g. 18.5).

observacion

string

Optional teacher comment recorded alongside the grade.

evaluacion

object

The linked assessment. Contains the following properties:

Show evaluacion properties

evaluacion.id

integer

Assessment ID.

evaluacion.titulo

string

Assessment title.

evaluacion.porcentaje

number

Percentage weight of this assessment within the course.

evaluacion.fecha

string

Assessment date (ISO 8601 format).

evaluacion.curso

object

The Curso this assessment belongs to.

evaluacion.asignacionDocente

object

The teacher assignment associated with this assessment.

estudiante

object

The student who received this grade. Contains the following properties:

Show estudiante properties

estudiante.id

integer

Student record ID.

estudiante.codigo

string

Institutional student code.

estudiante.usuario

object

The linked Usuario (user account).

estudiante.grado

object

The grade level or classroom the student belongs to.

Example

cURL

curl --request GET \
  --url http://localhost:8080/api/notas \
  --header 'Authorization: Bearer <your-token>'

Response

[
  {
    "id": 1,
    "nota": 18.5,
    "observacion": "Excelente desempeño",
    "evaluacion": {
      "id": 1,
      "titulo": "Examen Parcial",
      "porcentaje": 30,
      "fecha": "2026-05-10",
      "curso": { "id": 1, "nombre": "Matemáticas" },
      "asignacionDocente": { "id": 2 }
    },
    "estudiante": {
      "id": 1,
      "codigo": "EST-001",
      "usuario": { "id": 5, "nombre": "Ana García" },
      "grado": { "id": 3, "nombre": "3° Secundaria" }
    }
  }
]

Record a grade

Creates a new Nota record linking a student to an evaluation with a numeric score. Reference existing records by their id; Hibernate will resolve the full objects from the database.

Both evaluacion.id and estudiante.id must reference records that already exist. If either ID is invalid, Hibernate will throw a constraint error and the request will fail.

Request body

nota

number

required

The numeric score to record (e.g. 18.5).

observacion

string

Optional teacher comment or observation.

evaluacion

object

required

Reference to an existing Evaluacion by ID: { "id": 1 }.

estudiante

object

required

Reference to an existing Estudiante by ID: { "id": 1 }.

Example

cURL

curl --request POST \
  --url http://localhost:8080/api/notas \
  --header 'Authorization: Bearer <your-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "nota": 18.5,
    "observacion": "Excelente desempeño",
    "evaluacion": { "id": 1 },
    "estudiante": { "id": 1 }
  }'

Response

{
  "id": 42,
  "nota": 18.5,
  "observacion": "Excelente desempeño",
  "evaluacion": { "id": 1 },
  "estudiante": { "id": 1 }
}

Get grades for a student

Returns all Nota records where estudiante.id matches the given value. The filter is applied via a JPQL query on the repository layer — the result shape is identical to GET /api/notas but scoped to a single student.

The id path parameter is the Estudiante entity ID, not the Usuario (user account) ID. A student’s Estudiante ID is included in the grade records returned by GET /api/notas under the estudiante.id field.

Path parameter

integer

required

The Estudiante ID to filter grades by.

Example

cURL

curl --request GET \
  --url http://localhost:8080/api/notas/estudiante/1 \
  --header 'Authorization: Bearer <your-token>'

Response

[
  {
    "id": 42,
    "nota": 18.5,
    "observacion": "Excelente desempeño",
    "evaluacion": {
      "id": 1,
      "titulo": "Examen Parcial",
      "porcentaje": 30,
      "fecha": "2026-05-10",
      "curso": { "id": 1, "nombre": "Matemáticas" },
      "asignacionDocente": { "id": 2 }
    },
    "estudiante": {
      "id": 1,
      "codigo": "EST-001",
      "usuario": { "id": 5, "nombre": "Ana García" },
      "grado": { "id": 3, "nombre": "3° Secundaria" }
    }
  }
]

Error codes

Status	Meaning
`401 Unauthorized`	The `Authorization` header is missing or the token is invalid.
Hibernate constraint error	`evaluacion.id` or `estudiante.id` does not reference an existing record. Ensure both entities exist before posting a grade.

Auth

Courses & Grades

Role Endpoints

Grades API — record and retrieve student scores

List all grades

Response fields

Example

Record a grade

Request body

Example

Get grades for a student

Path parameter

Example

Error codes

Build docs developers (and LLMs) love

Auth

Courses & Grades

Role Endpoints

Documentation Index

​List all grades

​Response fields

​Example

​Record a grade

​Request body

​Example

​Get grades for a student

​Path parameter

​Example

​Error codes

Build docs developers (and LLMs) love

List all grades

Response fields

Example

Record a grade

Request body

Example

Get grades for a student

Path parameter

Example

Error codes