Courses & Sections API: Cursos, Paralelos, Subjects

Cole organizes the academic calendar around academic periods (periodos). Within each period, a curso (course/grade level) groups students by academic year or programme, while a paralelo (section) is a specific class within that course — for example, “Décimo A” or “Décimo B”. Subjects (materias) are the individual disciplines taught across courses and paralelos. All endpoints require a valid Bearer token obtained from the authentication flow. Director-only routes additionally require the role:director middleware to be satisfied.

Cursos

Cursos are scoped to an academic period. Every POST, PUT, and DELETE operation is restricted to users with the director role. The period must be active (activo = true) before new cursos can be created.

List Cursos

Requires auth:sanctum. Available to all authenticated roles within the tenant.

GET /api/periodos/{periodo}/cursos

Returns all cursos belonging to the given period, including their nested paralelos. Path Parameters

periodo

integer

required

The ID of the academic period.

Example Request

curl -X GET https://your-domain.com/api/periodos/1/cursos \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Example Response

[
  {
    "id": 1,
    "nombre": "Décimo",
    "nivel": "Básica Superior",
    "descripcion": "Décimo año de educación básica",
    "estado": true,
    "academic_period_id": 1,
    "created_at": "2026-04-07T10:00:00.000000Z",
    "updated_at": "2026-04-07T10:00:00.000000Z",
    "periodo": {
      "id": 1,
      "nombre": "2026-2027"
    },
    "paralelos": [
      { "id": 1, "nombre": "A", "turno": "Matutino", "capacidad": 35 },
      { "id": 2, "nombre": "B", "turno": "Matutino", "capacidad": 35 }
    ]
  }
]

Get Curso

GET /api/periodos/{periodo}/cursos/{id}

Returns a single curso with its paralelos. Path Parameters

periodo

integer

required

The ID of the academic period.

integer

required

The ID of the curso.

Example Request

curl -X GET https://your-domain.com/api/periodos/1/cursos/1 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Create Curso

Requires role:director. The academic period must be active.

POST /api/periodos/{periodo}/cursos

Path Parameters

periodo

integer

required

The ID of the academic period.

Request Body

nombre

string

required

Name of the course, e.g. "Décimo". Must be unique within the same tenant + period combination.

nivel

string

required

Academic level label, e.g. "Básica Superior" or "Bachillerato".

descripcion

string

Optional free-text description of the course.

Example Request

curl -X POST https://your-domain.com/api/periodos/1/cursos \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "nombre": "Décimo",
    "nivel": "Básica Superior",
    "descripcion": "Décimo año de educación básica"
  }'

Example Response 201 Created

{
  "id": 1,
  "nombre": "Décimo",
  "nivel": "Básica Superior",
  "descripcion": "Décimo año de educación básica",
  "estado": true,
  "academic_period_id": 1,
  "created_at": "2026-04-07T10:00:00.000000Z",
  "updated_at": "2026-04-07T10:00:00.000000Z",
  "periodo": {
    "id": 1,
    "nombre": "2026-2027"
  }
}

Error Responses

Status	Condition
`403 Forbidden`	The academic period is inactive.
`422 Unprocessable Entity`	Validation failed (missing required fields).

Update Curso

Requires role:director.

PUT /api/periodos/{periodo}/cursos/{id}

Path Parameters

periodo

integer

required

The ID of the academic period.

integer

required

The ID of the curso to update.

Request Body

nombre

string

Updated course name.

nivel

string

Updated academic level.

descripcion

string

Updated description.

estado

boolean

Set to false to deactivate the course.

Example Request

curl -X PUT https://your-domain.com/api/periodos/1/cursos/1 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "descripcion": "Updated description" }'

Delete Curso

Requires role:director.

DELETE /api/periodos/{periodo}/cursos/{id}

Path Parameters

periodo

integer

required

The ID of the academic period.

integer

required

The ID of the curso to delete.

Example Request

curl -X DELETE https://your-domain.com/api/periodos/1/cursos/1 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Example Response 200 OK

{ "message": "Curso eliminado" }

List Paralelos for a Curso

Requires role:director.

GET /api/periodos/{periodo}/cursos/{id}/paralelos

Returns all paralelos (sections) that belong to the specified curso. Path Parameters

periodo

integer

required

The ID of the academic period.

integer

required

The ID of the curso.

Example Request

curl -X GET https://your-domain.com/api/periodos/1/cursos/1/paralelos \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Example Response

{
  "data": [
    { "id": 1, "nombre": "A", "turno": "Matutino", "capacidad": 35, "curso_id": 1 },
    { "id": 2, "nombre": "B", "turno": "Matutino", "capacidad": 35, "curso_id": 1 }
  ]
}

Paralelos

Paralelos (sections) are child resources of a curso. They are not period-scoped at the URL level but are implicitly scoped to the tenant because their parent curso_id is tenant-validated on write.

List Paralelos

Requires auth:sanctum.

GET /api/paralelos

Returns all paralelos in the tenant, each with the parent curso eagerly loaded. Example Request

curl -X GET https://your-domain.com/api/paralelos \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Example Response

[
  {
    "id": 1,
    "nombre": "A",
    "turno": "Matutino",
    "capacidad": 35,
    "curso_id": 1,
    "tenant_id": 1,
    "curso": {
      "id": 1,
      "nombre": "Décimo",
      "nivel": "Básica Superior"
    }
  }
]

Get Paralelo

GET /api/paralelos/{id}

Path Parameters

integer

required

The ID of the paralelo.

Create Paralelo

Requires role:director.

POST /api/paralelos

The combination of curso_id + nombre must be unique within the tenant. Request Body

curso_id

integer

required

ID of the parent curso. Must belong to the authenticated user’s tenant.

nombre

string

required

Label for the section, e.g. "A", "B", or "Vespertino".

turno

string

School shift, e.g. "Matutino" or "Vespertino".

capacidad

integer

Maximum number of students allowed in this section.

Example Request

curl -X POST https://your-domain.com/api/paralelos \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "curso_id": 1,
    "nombre": "A",
    "turno": "Matutino",
    "capacidad": 35
  }'

Example Response 201 Created

{
  "id": 1,
  "curso_id": 1,
  "nombre": "A",
  "turno": "Matutino",
  "capacidad": 35,
  "tenant_id": 1,
  "created_at": "2026-04-07T10:00:00.000000Z",
  "updated_at": "2026-04-07T10:00:00.000000Z"
}

Error Responses

Status	Condition
`403 Forbidden`	The `curso_id` does not belong to the authenticated user’s tenant.
`422 Unprocessable Entity`	Validation failed or section name already exists for the curso.

Update Paralelo

Requires auth:sanctum. Available to all authenticated roles.

PUT /api/paralelos/{id}

Path Parameters

integer

required

The ID of the paralelo to update.

Request Body

curso_id

integer

required

ID of the parent curso (must belong to the tenant).

nombre

string

required

Updated section label.

turno

string

Updated school shift.

capacidad

integer

Updated student capacity.

Example Request

curl -X PUT https://your-domain.com/api/paralelos/1 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "curso_id": 1, "nombre": "A", "capacidad": 40 }'

Delete Paralelo

Requires auth:sanctum. Available to all authenticated roles.

DELETE /api/paralelos/{id}

Path Parameters

integer

required

The ID of the paralelo to delete.

Example Request

curl -X DELETE https://your-domain.com/api/paralelos/1 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Example Response 200 OK

{ "message": "Paralelo eliminado correctamente" }

Subjects

Subjects (materias) are the individual disciplines — such as Mathematics, Science, or History — that can be taught by professors and scheduled within courses and sections.

List Subjects

Requires role:director or role:profesor.

GET /api/subjects

Returns all subjects belonging to the tenant. Example Request

curl -X GET https://your-domain.com/api/subjects \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Example Response

[
  { "id": 1, "name": "Matemáticas", "tenant_id": 1 },
  { "id": 2, "name": "Ciencias Naturales", "tenant_id": 1 }
]

Get Subject

Requires role:director or role:profesor.

GET /api/subjects/{subject}

Path Parameters

subject

integer

required

The ID of the subject.

Create Subject

Requires role:director.

POST /api/subjects

Request Body

name

string

required

The name of the subject, e.g. "Matemáticas".

Example Request

curl -X POST https://your-domain.com/api/subjects \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "name": "Matemáticas" }'

Example Response 200 OK

{ "id": 1, "name": "Matemáticas", "tenant_id": 1 }

Update Subject

Requires role:director.

PUT /api/subjects/{subject}

Path Parameters

subject

integer

required

The ID of the subject to update.

Request Body

name

string

required

Updated subject name.

Example Request

curl -X PUT https://your-domain.com/api/subjects/1 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "name": "Matemáticas Avanzadas" }'

Delete Subject

Requires role:director.

DELETE /api/subjects/{subject}

Path Parameters

subject

integer

required

The ID of the subject to delete.

Example Request

curl -X DELETE https://your-domain.com/api/subjects/1 \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Example Response 200 OK

{ "message": "Materia eliminada" }

List Professors Teaching a Subject

Requires role:director.

GET /api/subjects/{id}/profesores

Returns all professors within the tenant who have been assigned to teach the specified subject. Path Parameters

integer

required

The ID of the subject.

Example Request

curl -X GET https://your-domain.com/api/subjects/1/profesores \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Example Response

{
  "data": [
    {
      "id": 1,
      "codigo_profesor": "PROF-001",
      "especialidad": "Matemáticas",
      "tenant_id": 1,
      "user": {
        "id": 2,
        "name": "Carlos Mendoza",
        "email": "cmendoza@school.edu"
      }
    }
  ]
}

data

array

Array of professor objects.

data[].id

integer

Internal ID of the professor record.

data[].codigo_profesor

string

Unique teacher code within the tenant.

data[].especialidad

string

Teacher’s area of specialization.

data[].user

object

Linked user account details (name and email).

Auth

Administration

Academic Management

Teaching

Parent & Student Portal

Circulares

Courses & Sections API: Cursos, Paralelos, Subjects

Cursos

List Cursos

Get Curso

Create Curso

Update Curso

Delete Curso

List Paralelos for a Curso

Paralelos

List Paralelos

Get Paralelo

Create Paralelo

Update Paralelo

Delete Paralelo

Subjects

List Subjects

Get Subject

Create Subject

Update Subject

Delete Subject

List Professors Teaching a Subject

Build docs developers (and LLMs) love

Auth

Administration

Academic Management

Teaching

Parent & Student Portal

Circulares

Documentation Index

​Cursos

​List Cursos

​Get Curso

​Create Curso

​Update Curso

​Delete Curso

​List Paralelos for a Curso

​Paralelos

​List Paralelos

​Get Paralelo

​Create Paralelo

​Update Paralelo

​Delete Paralelo

​Subjects

​List Subjects

​Get Subject

​Create Subject

​Update Subject

​Delete Subject

​List Professors Teaching a Subject

Build docs developers (and LLMs) love

Cursos

List Cursos

Get Curso

Create Curso

Update Curso

Delete Curso

List Paralelos for a Curso

Paralelos

List Paralelos

Get Paralelo

Create Paralelo

Update Paralelo

Delete Paralelo

Subjects

List Subjects

Get Subject

Create Subject

Update Subject

Delete Subject

List Professors Teaching a Subject