Teachers API: Professors, Assignments, and Schedules

Cole’s teacher management spans two concerns: professor profiles (who a teacher is and which subjects they can teach) and asignaciones docentes (which specific class section, within a period, a teacher is actually scheduled to deliver). Creating an asignación automatically validates schedule conflicts for both the professor and the target section, ensuring no double-booking occurs. All requests must include a valid Bearer token. Routes marked director require the authenticated user to hold the director role.

Profesores

List Professors

Requires role:director.

GET /api/profesores

Returns all professor profiles for the authenticated user’s tenant, with their linked user account and assigned subjects. Example Request

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

Example Response

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

Create Professor

Requires role:director.

POST /api/profesores

Creates a new user account, assigns it the profesor role, and creates the linked professor profile in one atomic operation. Request Body

name

string

required

Full name of the teacher, e.g. "Carlos Mendoza".

string

required

Unique email address used for login. Must not already exist in the users table.

password

string

required

Initial password. Minimum 6 characters. Stored as a bcrypt hash.

codigo_profesor

string

required

Unique teacher code within the tenant, e.g. "PROF-001". Scoped to tenant_id, so the same code can exist across different schools.

especialidad

string

Optional specialization label, e.g. "Matemáticas" or "Ciencias".

Example Request

curl -X POST https://your-domain.com/api/profesores \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Carlos Mendoza",
    "email": "cmendoza@school.edu",
    "password": "secret123",
    "codigo_profesor": "PROF-001",
    "especialidad": "Matemáticas"
  }'

Example Response 201 Created

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

message

string

Human-readable confirmation message.

data

object

The newly created professor record.

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 with id, name, and email.

Error Responses

Status	Condition
`422 Unprocessable Entity`	Validation failed (e.g. duplicate email or `codigo_profesor`).

Get Professor

Requires role:director.

GET /api/profesores/{id}

Returns a professor with their user account and subjects. Path Parameters

integer

required

The ID of the professor.

Example Request

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

Update Professor

Requires role:director.

PUT /api/profesores/{id}

Partially updates the professor’s user account or profile. All fields are optional; only provided fields are updated. Path Parameters

integer

required

The ID of the professor to update.

Request Body

name

string

Updated full name.

string

Updated email. Must be unique in the users table, excluding the current user’s record.

password

string

New password. Minimum 6 characters. Leave blank to keep the existing password.

codigo_profesor

string

Updated teacher code. Must be unique within the tenant.

especialidad

string

Updated specialization.

Example Request

curl -X PUT https://your-domain.com/api/profesores/1 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "especialidad": "Física y Matemáticas" }'

Delete Professor

Requires role:director.

DELETE /api/profesores/{id}

Deletes the professor record, removes all subject assignments (profesor_subjects), and deletes the linked user account. Path Parameters

integer

required

The ID of the professor to delete.

Example Request

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

Example Response 200 OK

{ "message": "Profesor eliminado correctamente" }

Assign Subject to Professor

Requires role:director.

POST /api/profesores/asignar-materia

Creates a profesor_subject link so the teacher is eligible to be scheduled for that subject. Both the professor and subject must belong to the same tenant. Request Body

profesor_id

integer

required

ID of the professor. Must exist within the authenticated tenant.

subject_id

integer

required

ID of the subject to assign. Must exist within the same tenant.

Example Request

curl -X POST https://your-domain.com/api/profesores/asignar-materia \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "profesor_id": 1, "subject_id": 1 }'

Example Response 201 Created

{
  "message": "Materia asignada correctamente",
  "data": {
    "id": 5,
    "profesor_id": 1,
    "subject_id": 1,
    "tenant_id": 1
  }
}

Error Responses

Status	Condition
`403 Forbidden`	Professor and subject belong to different tenants.
`409 Conflict`	Subject is already assigned to this professor.
`422 Unprocessable Entity`	`profesor_id` or `subject_id` not found within the tenant.

Remove Subject from Professor

Requires role:director.

POST /api/profesores/quitar-materia

Removes the profesor_subject link between a professor and a subject. Request Body

profesor_id

integer

required

ID of the professor.

subject_id

integer

required

ID of the subject to unassign.

Example Request

curl -X POST https://your-domain.com/api/profesores/quitar-materia \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "profesor_id": 1, "subject_id": 1 }'

Example Response 200 OK

{ "message": "Materia eliminada correctamente" }

Error Responses

Status	Condition
`404 Not Found`	The professor–subject relationship does not exist.

List Professor’s Subjects

Requires role:director.

GET /api/profesores/{id}/subjects

Returns all subjects currently assigned to the given professor. Path Parameters

integer

required

The ID of the professor.

Example Request

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

Example Response

{
  "data": [
    { "id": 1, "name": "Matemáticas" },
    { "id": 3, "name": "Física" }
  ]
}

Get Professor Schedule

Requires role:director.

GET /api/profesores/{id}/horario

Returns the professor’s full weekly schedule, derived from their class assignments (asignaciones). Entries are grouped by day in calendar order (Lunes → Domingo) and sorted by hora_inicio within each day. Path Parameters

integer

required

The ID of the professor.

Example Request

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

Example Response

{
  "profesor": {
    "id": 1,
    "nombre": "Carlos Mendoza",
    "codigo": "PROF-001"
  },
  "horario": {
    "Lunes": [
      {
        "id": 3,
        "dia": "Lunes",
        "hora_inicio": "07:00:00",
        "hora_fin": "08:00:00",
        "materia": "Matemáticas",
        "curso": "Décimo",
        "paralelo": "A"
      }
    ],
    "Martes": [
      {
        "id": 4,
        "dia": "Martes",
        "hora_inicio": "09:00:00",
        "hora_fin": "10:00:00",
        "materia": "Física",
        "curso": "Noveno",
        "paralelo": "B"
      }
    ]
  }
}

profesor

object

Identifying information for the professor.

profesor.id

integer

Internal professor ID.

profesor.nombre

string

Teacher’s full name from the linked user account.

profesor.codigo

string

Unique teacher code.

horario

object

Keys are day names in Spanish (Lunes, Martes, …Domingo). Each value is an array of schedule slots sorted by hora_inicio.

horario[day][].id

integer

The asignación docente ID.

horario[day][].dia

string

Day name in Spanish.

horario[day][].hora_inicio

string

Start time in HH:MM:SS format.

horario[day][].hora_fin

string

End time in HH:MM:SS format.

horario[day][].materia

string

Subject name.

horario[day][].curso

string

Course name.

horario[day][].paralelo

string

Section label.

Asignaciones Docentes

An asignación docente ties a professor, a subject, a course, and a section together within an academic period. It also holds one or more horario slots (day + start/end times). The API prevents double-booking: the same section cannot have two subjects overlapping in time, and the same professor cannot be in two places at once within the same period.

List Asignaciones

Requires role:director.

GET /api/periodos/{periodo}/asignaciones

Returns all class assignments for the period, optionally filtered by subject or professor. Path Parameters

periodo

integer

required

The ID of the academic period.

Query Parameters

subject_id

integer

Filter assignments to a specific subject.

profesor_id

integer

Filter assignments to a specific professor.

Example Request

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

Create Asignación

Requires role:director.

POST /api/periodos/{periodo}/asignaciones

Creates the assignment and persists all supplied schedule slots in one request. The API checks:

The curso_id belongs to the given period.
The professor has the subject_id assigned to them (profesor_subjects table).
The paralelo_id belongs to the curso_id.
No existing assignment already exists for that exact combination.
No time conflicts exist for the section or professor within the period.

Path Parameters

periodo

integer

required

The ID of the academic period.

Request Body

profesor_id

integer

required

ID of the professor being assigned.

subject_id

integer

required

ID of the subject being taught.

curso_id

integer

required

ID of the course. Must belong to the given academic period.

paralelo_id

integer

required

ID of the section. Must belong to the given curso_id.

horarios

array

required

At least one schedule slot is required. Each element must contain dia, hora_inicio, and hora_fin.

horarios[].dia

string

required

Day of the week in Spanish. Accepted values: Lunes, Martes, Miercoles, Jueves, Viernes, Sabado, Domingo.

horarios[].hora_inicio

string

required

Start time in HH:MM or HH:MM:SS format, e.g. "07:00".

horarios[].hora_fin

string

required

End time in HH:MM or HH:MM:SS format. Must be after hora_inicio.

Example Request

curl -X POST https://your-domain.com/api/periodos/1/asignaciones \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "profesor_id": 1,
    "subject_id": 1,
    "curso_id": 1,
    "paralelo_id": 1,
    "horarios": [
      { "dia": "Lunes",   "hora_inicio": "07:00", "hora_fin": "08:00" },
      { "dia": "Miercoles", "hora_inicio": "07:00", "hora_fin": "08:00" }
    ]
  }'

Example Response 201 Created

{
  "message": "Asignación creada correctamente",
  "data": {
    "id": 3,
    "profesor_id": 1,
    "subject_id": 1,
    "curso_id": 1,
    "paralelo_id": 1,
    "academic_period_id": 1,
    "profesor": {
      "id": 1,
      "codigo_profesor": "PROF-001",
      "user": { "id": 2, "name": "Carlos Mendoza" }
    },
    "subject": { "id": 1, "name": "Matemáticas" },
    "curso": { "id": 1, "nombre": "Décimo" },
    "paralelo": { "id": 1, "nombre": "A" },
    "horarios": [
      { "id": 1, "dia": "Lunes",     "hora_inicio": "07:00:00", "hora_fin": "08:00:00" },
      { "id": 2, "dia": "Miercoles", "hora_inicio": "07:00:00", "hora_fin": "08:00:00" }
    ]
  }
}

message

string

Confirmation message.

data

object

The created assignment with all nested relationships loaded.

data.id

integer

Asignación docente ID.

data.horarios

array

Array of schedule slots created for this assignment.

data.horarios[].dia

string

Day of the week.

data.horarios[].hora_inicio

string

Start time.

data.horarios[].hora_fin

string

End time.

Error Responses

Status	Condition
`422 Unprocessable Entity`	Curso does not belong to the period; professor is not assigned to the subject; paralelo does not belong to the curso; schedule conflict for section or professor.
`422 Unprocessable Entity`	Duplicate assignment already exists.

Get Asignación

Requires role:director.

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

Path Parameters

periodo

integer

required

The ID of the academic period.

integer

required

The ID of the asignación.

Example Request

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

Delete Asignación

Requires role:director.

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

Path Parameters

periodo

integer

required

The ID of the academic period.

integer

required

The ID of the asignación to remove.

Example Request

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

Example Response 200 OK

{ "message": "Asignación eliminada correctamente" }

View Own Classes (Professor)

Requires role:profesor.

GET /api/periodos/{periodo}/asignaciones/mis-clases

Returns all class assignments for the currently authenticated professor within the given period. The professor is resolved automatically from the authenticated user’s linked profesor record. Path Parameters

periodo

integer

required

The ID of the academic period.

Example Request

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

Example Response

{
  "asignaciones": [
    {
      "id": 3,
      "curso": "Décimo",
      "paralelo": "A",
      "materia": "Matemáticas",
      "curso_id": 1,
      "paralelo_id": 1,
      "subject_id": 1
    }
  ]
}

View Section Schedule

Requires role:director.

GET /api/periodos/{periodo}/cursos/{curso}/paralelos/{paralelo}/horario

Returns the full weekly timetable for a specific course section within a period. Each slot includes the subject name and teacher name. Path Parameters

periodo

integer

required

The ID of the academic period.

curso

integer

required

The ID of the course.

paralelo

integer

required

The ID of the section.

Example Request

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

Example Response

{
  "curso_id": 1,
  "paralelo_id": 1,
  "periodo_id": 1,
  "horario": {
    "Lunes": [
      {
        "id": 1,
        "dia": "Lunes",
        "hora_inicio": "07:00:00",
        "hora_fin": "08:00:00",
        "materia": "Matemáticas",
        "profesor": "Carlos Mendoza"
      }
    ],
    "Martes": [
      {
        "id": 5,
        "dia": "Martes",
        "hora_inicio": "08:00:00",
        "hora_fin": "09:00:00",
        "materia": "Ciencias Naturales",
        "profesor": "Ana Torres"
      }
    ]
  }
}

Add Schedule Slot to Asignación

Requires role:director.

POST /api/asignaciones/{id}/horarios

Adds a single schedule slot to an existing asignación. Performs the same conflict checks as the full assignment creation (no overlapping slots for the section or professor). Path Parameters

integer

required

The ID of the asignación docente.

Request Body

dia

string

required

Day of the week. Accepted values: Lunes, Martes, Miercoles, Jueves, Viernes, Sabado, Domingo.

hora_inicio

string

required

Start time in HH:MM or HH:MM:SS format.

hora_fin

string

required

End time. Must be after hora_inicio.

Example Request

curl -X POST https://your-domain.com/api/asignaciones/3/horarios \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "dia": "Viernes",
    "hora_inicio": "10:00",
    "hora_fin": "11:00"
  }'

Example Response 200 OK

{
  "message": "Horario agregado correctamente",
  "data": {
    "id": 7,
    "asignacion_docente_id": 3,
    "dia": "Viernes",
    "hora_inicio": "10:00:00",
    "hora_fin": "11:00:00"
  }
}

Error Responses

Status	Condition
`422 Unprocessable Entity`	Section already has a subject in that time slot.
`422 Unprocessable Entity`	Professor already has a class in that time slot.
`422 Unprocessable Entity`	Identical slot already exists on this assignment.

Auth

Administration

Academic Management

Teaching

Parent & Student Portal

Circulares

Teachers API: Professors, Assignments, and Schedules

Profesores

List Professors

Create Professor

Get Professor

Update Professor

Delete Professor

Assign Subject to Professor

Remove Subject from Professor

List Professor’s Subjects

Get Professor Schedule

Asignaciones Docentes

List Asignaciones

Create Asignación

Get Asignación

Delete Asignación

View Own Classes (Professor)

View Section Schedule

Add Schedule Slot to Asignación

Build docs developers (and LLMs) love

Auth

Administration

Academic Management

Teaching

Parent & Student Portal

Circulares

Documentation Index

​Profesores

​List Professors

​Create Professor

​Get Professor

​Update Professor

​Delete Professor

​Assign Subject to Professor

​Remove Subject from Professor

​List Professor’s Subjects

​Get Professor Schedule

​Asignaciones Docentes

​List Asignaciones

​Create Asignación

​Get Asignación

​Delete Asignación

​View Own Classes (Professor)

​View Section Schedule

​Add Schedule Slot to Asignación

Build docs developers (and LLMs) love

Profesores

List Professors

Create Professor

Get Professor

Update Professor

Delete Professor

Assign Subject to Professor

Remove Subject from Professor

List Professor’s Subjects

Get Professor Schedule

Asignaciones Docentes

List Asignaciones

Create Asignación

Get Asignación

Delete Asignación

View Own Classes (Professor)

View Section Schedule

Add Schedule Slot to Asignación