Grades API: Criteria, Weighted Grades, and Gradebook

The Grades API covers the full grading workflow in Cole: directors and professors define evaluation periods within an academic period; professors then attach weighted criteria (e.g. “Quiz 20 %, Project 30 %, Final Exam 50 %”) to each assignment within those periods; grades are entered per criterion per student; and the gradebook endpoint computes weighted averages automatically. Averages and report cards aggregate those results across all evaluation periods.

Evaluation period routes require role:director or role:profesor. All criteria, grade, gradebook, and average routes require role:profesor or role:director as indicated per section. All routes require a valid Sanctum bearer token. Criteria and grade entry routes additionally enforce professor ownership — a professor can only manage criteria and grades for their own assignments.

Evaluation Periods

Evaluation periods group criteria into named reporting windows (e.g. “Primer Quimestre”, “Segundo Quimestre”). They are scoped to an academic period.

List Evaluation Periods

GET /api/periodos/{periodo}/periodos-evaluacion

periodo

integer

required

The academic period ID.

Returns all evaluation periods for the academic period ordered by orden ascending, each including its parent academicPeriod. Example response 200 OK

[
  { "id": 1, "academic_period_id": 5, "nombre": "Primer Quimestre", "orden": 1 },
  { "id": 2, "academic_period_id": 5, "nombre": "Segundo Quimestre", "orden": 2 }
]

Create an Evaluation Period

POST /api/periodos/{periodo}/periodos-evaluacion

periodo

integer

required

The academic period ID.

nombre

string

required

Name of the evaluation period (max 255 characters), e.g. "Primer Quimestre".

orden

integer

required

Sort order for this period within the academic year. Must be ≥ 1.

Example request

curl -X POST https://your-tenant.coleapp.io/api/periodos/5/periodos-evaluacion \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "nombre": "Primer Quimestre", "orden": 1 }'

Example response 201 Created

{
  "id": 1,
  "academic_period_id": 5,
  "nombre": "Primer Quimestre",
  "orden": 1,
  "tenant_id": 3,
  "created_at": "2026-05-01T10:00:00.000000Z",
  "updated_at": "2026-05-01T10:00:00.000000Z"
}

Grading Criteria

Criteria represent the individual graded components within an evaluation period (e.g. “Tarea 1”, “Examen Parcial”). Each criterion carries a percentage weight; the sum of all criterion percentages for one assignment within one evaluation period cannot exceed 100.

If adding or updating a criterion would push the total percentage above 100 for that assignment + evaluation period combination, the API returns 422 Unprocessable Entity with the message: "La suma de porcentajes para esta materia en este periodo no puede superar 100%".

List Criteria for an Assignment

GET /api/criterios/asignacion/{asignacionId}

asignacionId

integer

required

The teacher assignment ID. The authenticated professor must own this assignment.

Returns all criteria for the assignment ordered by ID, each including its parent periodoEvaluacion.

List Criteria by Evaluation Period

GET /api/periodos-evaluacion/{periodoId}/criterios

periodoId

integer

required

The evaluation period ID.

Returns all criteria for that evaluation period regardless of assignment.

List Professor’s Own Criteria for an Evaluation Period

Returns only the criteria belonging to the authenticated professor’s assignments within the specified evaluation period.

GET /api/periodos-evaluacion/{periodo}/mis-criterios

periodo

integer

required

The evaluation period ID.

Each criterion in the response includes the evaluation period, the subject name, course name, and parallel name for context.

List Evaluation Periods That Have Criteria for an Assignment

Returns the evaluation periods that contain at least one criterion for the given assignment, ordered by orden.

GET /api/asignaciones/{asignacion}/periodos-evaluacion

asignacion

integer

required

The teacher assignment ID. The authenticated professor must own this assignment.

Example response 200 OK

[
  { "id": 1, "nombre": "Primer Quimestre", "orden": 1 },
  { "id": 2, "nombre": "Segundo Quimestre", "orden": 2 }
]

Create a Criterion

POST /api/criterios/asignacion/{asignacionId}

asignacionId

integer

required

The teacher assignment ID. Must be owned by the authenticated professor.

periodo_evaluacion_id

integer

required

The evaluation period this criterion belongs to. Must exist in periodos_evaluacion.

nombre

string

required

Criterion name (max 255 characters), e.g. "Tarea 1", "Examen Final".

porcentaje

number

required

Weight of this criterion as a percentage (1–100). The running total for the assignment + evaluation period combination cannot exceed 100.

Example request

curl -X POST https://your-tenant.coleapp.io/api/criterios/asignacion/18 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "periodo_evaluacion_id": 1,
    "nombre": "Examen Parcial",
    "porcentaje": 40
  }'

Example response 201 Created

{
  "id": 9,
  "asignacion_docente_id": 18,
  "periodo_evaluacion_id": 1,
  "nombre": "Examen Parcial",
  "porcentaje": 40,
  "tenant_id": 3,
  "created_at": "2026-05-10T09:00:00.000000Z",
  "updated_at": "2026-05-10T09:00:00.000000Z"
}

Update a Criterion

PUT /api/criterios/{criterioId}

criterioId

integer

required

The criterion ID. Must belong to the authenticated professor’s assignment.

nombre

string

required

Updated criterion name (max 255 characters).

porcentaje

number

required

Updated percentage weight (1–100). Validation checks the sum of all other criteria in the same assignment + evaluation period, ensuring the total stays ≤ 100.

Example response 200 OK

{
  "id": 9,
  "nombre": "Examen Parcial",
  "porcentaje": 35,
  "updated_at": "2026-05-11T10:00:00.000000Z"
}

Delete a Criterion

DELETE /api/criterios/{criterioId}

criterioId

integer

required

The criterion ID. Must belong to the authenticated professor’s assignment.

Example response 200 OK

{ "message": "Criterio eliminado correctamente" }

Grade Entry

Grades are entered per criterion. Each grade is a numeric value between 0 and 100. The weighted average is computed by the gradebook endpoint rather than stored — Nota records contain the raw score only.

List Grades for a Criterion

Returns all enrolled students with their raw grade (or null) for the given criterion.

GET /api/criterios/{criterio}/notas

criterio

integer

required

The criterion ID. Must belong to the authenticated professor’s assignment.

Example response 200 OK

[
  {
    "id": 101,
    "nombre": "Ana Torres",
    "nota_id": 44,
    "nota": 87.5,
    "observacion": null
  },
  {
    "id": 102,
    "nombre": "Luis Ramírez",
    "nota_id": null,
    "nota": null,
    "observacion": null
  }
]

Save Grades for a Criterion

Uses updateOrCreate internally, so this endpoint is safe to call multiple times — existing grade records are updated and new ones are created as needed. Send the full roster on each call.

POST /api/criterios/{criterio}/notas

criterio

integer

required

The criterion ID. Must belong to the authenticated professor’s assignment.

notas

array

required

Array of grade objects, one per student.

Show notas[]

estudiante_id

integer

required

Student ID. Must exist in the estudiantes table.

nota

number

required

Numeric grade from 0 to 100 (inclusive).

observacion

string

Optional note about the grade. Nullable.

Example request

curl -X POST https://your-tenant.coleapp.io/api/criterios/9/notas \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "notas": [
      { "estudiante_id": 101, "nota": 87.5 },
      { "estudiante_id": 102, "nota": 72.0, "observacion": "Mejoró en la segunda parte" },
      { "estudiante_id": 103, "nota": 95.0 }
    ]
  }'

Example response 200 OK

{ "message": "Notas guardadas correctamente" }

Gradebook

Full Gradebook — by Evaluation Period

Returns the complete gradebook for one assignment scoped to one evaluation period, including all criteria columns and the weighted average per student.

GET /api/asignaciones/{asignacion}/periodos-evaluacion/{periodo}/libro-calificaciones

asignacion

integer

required

The teacher assignment ID.

periodo

integer

required

The evaluation period ID.

criterios

array

Column definitions for the gradebook.

Show criterios[]

integer

Criterion ID.

nombre

string

Criterion name.

porcentaje

number

Weight as a percentage.

estudiantes

array

One row per enrolled student.

Show estudiantes[]

estudiante_id

integer

Student ID.

estudiante

string

Student full name.

notas

array

Array of criterion score entries (aligned with criterios above).

Show notas[]

criterio_id

integer

Criterion ID.

criterio

string

Criterion name.

porcentaje

number

Criterion weight.

nota

number

Raw score (0–100). Defaults to 0 if not yet entered.

promedio

number

Weighted average computed as Σ(nota × porcentaje / 100), rounded to 2 decimal places.

Example response 200 OK

{
  "criterios": [
    { "id": 9,  "nombre": "Examen Parcial", "porcentaje": 40 },
    { "id": 10, "nombre": "Proyecto Final", "porcentaje": 60 }
  ],
  "estudiantes": [
    {
      "estudiante_id": 101,
      "estudiante": "Ana Torres",
      "notas": [
        { "criterio_id": 9,  "criterio": "Examen Parcial", "porcentaje": 40, "nota": 87.5 },
        { "criterio_id": 10, "criterio": "Proyecto Final",  "porcentaje": 60, "nota": 92.0 }
      ],
      "promedio": 90.2
    },
    {
      "estudiante_id": 102,
      "estudiante": "Luis Ramírez",
      "notas": [
        { "criterio_id": 9,  "criterio": "Examen Parcial", "porcentaje": 40, "nota": 72.0 },
        { "criterio_id": 10, "criterio": "Proyecto Final",  "porcentaje": 60, "nota": 78.0 }
      ],
      "promedio": 75.6
    }
  ]
}

Alternative Gradebook — All Periods

Returns the same gradebook structure for an assignment but across all evaluation periods (not filtered to one). Useful for a complete at-a-glance view.

GET /api/asignaciones/{asignacion}/libro-calificaciones

asignacion

integer

required

The teacher assignment ID.

Response shape is identical to the period-scoped gradebook above.

Averages and Report Cards

Average and report card endpoints are accessible to users with role:profesor or role:director.

Average for an Evaluation Period

Returns the weighted average per student for all grades within the specified evaluation period.

GET /api/periodos-evaluacion/{periodoId}/promedio

periodoId

integer

required

The evaluation period ID.

Example response 200 OK

[
  { "estudiante_id": 101, "nombre": "Ana Torres",   "promedio": 90.2 },
  { "estudiante_id": 102, "nombre": "Luis Ramírez", "promedio": 75.6 }
]

Final Average for a Student

Computes the overall final average for a student by averaging the weighted averages across all evaluation periods in which they have grades.

GET /api/estudiantes/{estudiante}/promedio-final

estudiante

integer

required

The student ID.

estudiante_id

integer

The student ID.

promedio_final

number

Final average rounded to 2 decimal places, computed as mean(promedio_per_period).

Example response 200 OK

{
  "estudiante_id": 101,
  "promedio_final": 87.65
}

Full Report Card (Boletín) for a Student

Returns the student’s name, their weighted average per evaluation period, and their overall final average.

GET /api/estudiantes/{estudiante}/boletin

estudiante

integer

required

The student ID.

estudiante

string

Student full name.

periodos

array

One entry per evaluation period in which the student has grades.

Show periodos[]

periodo

string

Evaluation period name (e.g. "Primer Quimestre").

promedio

number

Weighted average for that period, rounded to 2 decimal places.

promedio_final

number

Arithmetic mean of all period averages, rounded to 2 decimal places.

Example response 200 OK

{
  "estudiante": "Ana Torres",
  "periodos": [
    { "periodo": "Primer Quimestre",  "promedio": 90.2 },
    { "periodo": "Segundo Quimestre", "promedio": 85.1 }
  ],
  "promedio_final": 87.65
}

Auth

Administration

Academic Management

Teaching

Parent & Student Portal

Circulares

Grades API: Criteria, Weighted Grades, and Gradebook

Evaluation Periods

List Evaluation Periods

Create an Evaluation Period

Grading Criteria

List Criteria for an Assignment

List Criteria by Evaluation Period

List Professor’s Own Criteria for an Evaluation Period

List Evaluation Periods That Have Criteria for an Assignment

Create a Criterion

Update a Criterion

Delete a Criterion

Grade Entry

List Grades for a Criterion

Save Grades for a Criterion

Gradebook

Full Gradebook — by Evaluation Period

Alternative Gradebook — All Periods

Averages and Report Cards

Average for an Evaluation Period

Final Average for a Student

Full Report Card (Boletín) for a Student

Build docs developers (and LLMs) love

Auth

Administration

Academic Management

Teaching

Parent & Student Portal

Circulares

Documentation Index

​Evaluation Periods

​List Evaluation Periods

​Create an Evaluation Period

​Grading Criteria

​List Criteria for an Assignment

​List Criteria by Evaluation Period

​List Professor’s Own Criteria for an Evaluation Period

​List Evaluation Periods That Have Criteria for an Assignment

​Create a Criterion

​Update a Criterion

​Delete a Criterion

​Grade Entry

​List Grades for a Criterion

​Save Grades for a Criterion

​Gradebook

​Full Gradebook — by Evaluation Period

​Alternative Gradebook — All Periods

​Averages and Report Cards

​Average for an Evaluation Period

​Final Average for a Student

​Full Report Card (Boletín) for a Student

Build docs developers (and LLMs) love

Evaluation Periods

List Evaluation Periods

Create an Evaluation Period

Grading Criteria

List Criteria for an Assignment

List Criteria by Evaluation Period

List Professor’s Own Criteria for an Evaluation Period

List Evaluation Periods That Have Criteria for an Assignment

Create a Criterion

Update a Criterion

Delete a Criterion

Grade Entry

List Grades for a Criterion

Save Grades for a Criterion

Gradebook

Full Gradebook — by Evaluation Period

Alternative Gradebook — All Periods

Averages and Report Cards

Average for an Evaluation Period

Final Average for a Student

Full Report Card (Boletín) for a Student