Academic Periods API: Manage School Years and Terms

An academic period (AcademicPeriod) represents a discrete interval of instruction — a school year, a semester, a trimester, or any other term the school defines. Every record that tracks student progress (enrollments, grades, attendance) is scoped to one academic period. Only one period may be active at a time per tenant; activating a new period automatically deactivates all others for that school. Periods are identified by a human-readable nombre (name), a start date (fecha_inicio), and an end date (fecha_fin), all of which are scoped to the authenticated user’s tenant_id. Directors have full CRUD access; professors can read periods and retrieve the currently active one.

All endpoints require an active Sanctum token. Include Authorization: Bearer <token> on every request.

GET /api/periodos

Returns all academic periods belonging to the authenticated user’s tenant. Authentication required: Authorization: Bearer <token> — role director or profesor

Response `200 OK`

Returns a JSON array of academic period objects.

integer

Unique period ID.

nombre

string

Name of the period. Example: "2026-I".

fecha_inicio

string

Start date in YYYY-MM-DD format.

fecha_fin

string

End date in YYYY-MM-DD format.

activo

boolean

Whether this period is currently active.

tenant_id

integer

The tenant this period belongs to.

created_at

string

ISO 8601 creation timestamp.

updated_at

string

ISO 8601 last-updated timestamp.

Example

curl -s -X GET https://your-cole-api.test/api/periodos \
  -H "Accept: application/json" \
  -H "Authorization: Bearer 5|directorToken..."

[
  {
    "id": 1,
    "nombre": "2025-II",
    "fecha_inicio": "2025-08-01",
    "fecha_fin": "2025-12-15",
    "activo": false,
    "tenant_id": 3,
    "created_at": "2025-07-15T08:00:00.000000Z",
    "updated_at": "2026-02-01T09:00:00.000000Z"
  },
  {
    "id": 2,
    "nombre": "2026-I",
    "fecha_inicio": "2026-02-01",
    "fecha_fin": "2026-07-15",
    "activo": true,
    "tenant_id": 3,
    "created_at": "2026-01-20T10:00:00.000000Z",
    "updated_at": "2026-02-01T09:00:00.000000Z"
  }
]

GET /api/periodos/activo

Returns the single period currently marked as activo = true for the authenticated user’s tenant. If no active period exists, the endpoint returns 404. Authentication required: Authorization: Bearer <token> — role director or profesor

This route is registered before GET /api/periodos/{id} in the router. The literal segment activo is not treated as a numeric ID. Always use the dedicated /activo route to fetch the active period rather than passing a string to /{id}.

Response `200 OK`

Returns the active academic period object (same shape as a single item from GET /api/periodos).

Error `404 Not Found`

{
  "message": "No hay periodo activo"
}

Example

curl -s -X GET https://your-cole-api.test/api/periodos/activo \
  -H "Accept: application/json" \
  -H "Authorization: Bearer 5|directorToken..."

{
  "id": 2,
  "nombre": "2026-I",
  "fecha_inicio": "2026-02-01",
  "fecha_fin": "2026-07-15",
  "activo": true,
  "tenant_id": 3,
  "created_at": "2026-01-20T10:00:00.000000Z",
  "updated_at": "2026-02-01T09:00:00.000000Z"
}

POST /api/periodos

Creates a new academic period for the authenticated director’s tenant. If activo is set to true, all other periods in the same tenant are automatically deactivated. Authentication required: Authorization: Bearer <token> — role director

Request body

nombre

string

required

Name of the academic period. Must be unique within the academic_periods table. Example: "2026-II".

fecha_inicio

string

required

Start date of the period. Must be a valid date in YYYY-MM-DD format.

fecha_fin

string

required

End date of the period. Must be a valid date after fecha_inicio.

activo

boolean

Optional. Defaults to false. If true, all other periods for this tenant are deactivated before the new period is created.

Response `201 Created`

Returns the newly created academic period object.

integer

Auto-generated period ID.

nombre

string

Period name as provided.

fecha_inicio

string

Start date.

fecha_fin

string

End date.

activo

boolean

Activation status.

tenant_id

integer

The tenant this period was created under.

created_at

string

ISO 8601 creation timestamp.

updated_at

string

ISO 8601 last-updated timestamp.

Example

curl -s -X POST https://your-cole-api.test/api/periodos \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer 5|directorToken..." \
  -d '{
    "nombre": "2026-II",
    "fecha_inicio": "2026-08-01",
    "fecha_fin": "2026-12-15",
    "activo": false
  }'

{
  "id": 3,
  "nombre": "2026-II",
  "fecha_inicio": "2026-08-01",
  "fecha_fin": "2026-12-15",
  "activo": false,
  "tenant_id": 3,
  "created_at": "2026-07-25T11:00:00.000000Z",
  "updated_at": "2026-07-25T11:00:00.000000Z"
}

GET /api/periodos/

Returns a single academic period by its numeric ID. Authentication required: Authorization: Bearer <token> — role director

Path parameters

integer

required

The numeric ID of the academic period to retrieve.

Response `200 OK`

Returns the academic period object. Returns 404 if the ID does not exist.

Example

curl -s -X GET https://your-cole-api.test/api/periodos/2 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer 5|directorToken..."

{
  "id": 2,
  "nombre": "2026-I",
  "fecha_inicio": "2026-02-01",
  "fecha_fin": "2026-07-15",
  "activo": true,
  "tenant_id": 3,
  "created_at": "2026-01-20T10:00:00.000000Z",
  "updated_at": "2026-02-01T09:00:00.000000Z"
}

PUT /api/periodos/

Updates an existing academic period. Supports two modes:

Full update: provide nombre, fecha_inicio, fecha_fin, and optionally activo. All required fields are validated.
Status-only update: provide only activo (single key). Skips name/date validation and just toggles the active flag.

In both modes, if the resulting activo value is true, all other periods in the tenant are set to activo = false. Authentication required: Authorization: Bearer <token> — role director

Path parameters

integer

required

The numeric ID of the academic period to update.

Request body

nombre

string

required

Updated name for the period. Required when doing a full update. Ignored in status-only mode.

fecha_inicio

string

required

Updated start date in YYYY-MM-DD format. Required when doing a full update.

fecha_fin

string

required

Updated end date. Must be after fecha_inicio. Required when doing a full update.

activo

boolean

Optional. If this is the only key sent, the endpoint performs a status-only update. If included alongside the other fields, it sets the activation status as part of the full update.

Response `200 OK`

Returns the updated academic period object.

Example — full update

curl -s -X PUT https://your-cole-api.test/api/periodos/3 \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer 5|directorToken..." \
  -d '{
    "nombre": "2026-II Revisado",
    "fecha_inicio": "2026-08-05",
    "fecha_fin": "2026-12-20",
    "activo": false
  }'

{
  "id": 3,
  "nombre": "2026-II Revisado",
  "fecha_inicio": "2026-08-05",
  "fecha_fin": "2026-12-20",
  "activo": false,
  "tenant_id": 3,
  "created_at": "2026-07-25T11:00:00.000000Z",
  "updated_at": "2026-07-25T14:00:00.000000Z"
}

Example — status-only update

curl -s -X PUT https://your-cole-api.test/api/periodos/3 \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer 5|directorToken..." \
  -d '{ "activo": true }'

{
  "id": 3,
  "nombre": "2026-II Revisado",
  "fecha_inicio": "2026-08-05",
  "fecha_fin": "2026-12-20",
  "activo": true,
  "tenant_id": 3,
  "created_at": "2026-07-25T11:00:00.000000Z",
  "updated_at": "2026-07-25T15:00:00.000000Z"
}

DELETE /api/periodos/

Permanently deletes an academic period record. Authentication required: Authorization: Bearer <token> — role director

Deleting an academic period may cascade to dependent records (courses, enrollments, grades) depending on the foreign key constraints defined on related tables. Ensure the period is no longer in use before deleting it.

Path parameters

integer

required

The numeric ID of the academic period to delete.

Response `200 OK`

message

string

Confirmation string. Example: "Periodo eliminado correctamente".

Example

curl -s -X DELETE https://your-cole-api.test/api/periodos/1 \
  -H "Accept: application/json" \
  -H "Authorization: Bearer 5|directorToken..."

{
  "message": "Periodo eliminado correctamente"
}

PATCH /api/periodos//activar

Activates the specified academic period. This is the canonical way to switch the active period: all other periods for the tenant are set to activo = false before the target period is set to activo = true. This guarantees at most one active period per tenant at all times. Authentication required: Authorization: Bearer <token> — role director

This endpoint is the preferred way to activate a period. It is equivalent to PUT /api/periodos/{id} with { "activo": true } as the only key, but is more explicit and does not require knowing the status-only update behavior of PUT.

Path parameters

integer

required

The numeric ID of the academic period to activate.

Response `200 OK`

message

string

Confirmation string. Example: "Periodo activado correctamente".

data

object

The updated academic period record with activo set to true.

Show data fields

integer

Period ID.

nombre

string

Period name.

fecha_inicio

string

Start date.

fecha_fin

string

End date.

activo

boolean

Always true in this response.

tenant_id

integer

Owning tenant ID.

created_at

string

ISO 8601 creation timestamp.

updated_at

string

ISO 8601 last-updated timestamp.

Example

curl -s -X PATCH https://your-cole-api.test/api/periodos/3/activar \
  -H "Accept: application/json" \
  -H "Authorization: Bearer 5|directorToken..."

{
  "message": "Periodo activado correctamente",
  "data": {
    "id": 3,
    "nombre": "2026-II Revisado",
    "fecha_inicio": "2026-08-05",
    "fecha_fin": "2026-12-20",
    "activo": true,
    "tenant_id": 3,
    "created_at": "2026-07-25T11:00:00.000000Z",
    "updated_at": "2026-07-25T16:00:00.000000Z"
  }
}

Auth

Administration

Academic Management

Teaching

Parent & Student Portal

Circulares

Academic Periods API: Manage School Years and Terms

GET /api/periodos

Response `200 OK`

Example

GET /api/periodos/activo

Response `200 OK`

Error `404 Not Found`

Example

POST /api/periodos

Request body

Response `201 Created`

Example

GET /api/periodos/

Path parameters

Response `200 OK`

Example

PUT /api/periodos/

Path parameters

Request body

Response `200 OK`

Example — full update

Example — status-only update

DELETE /api/periodos/

Path parameters

Response `200 OK`

Example

PATCH /api/periodos//activar

Path parameters

Response `200 OK`

Example

Build docs developers (and LLMs) love

Auth

Administration

Academic Management

Teaching

Parent & Student Portal

Circulares

Documentation Index

​GET /api/periodos

​Response 200 OK

​Example

​GET /api/periodos/activo

​Response 200 OK

​Error 404 Not Found

​Example

​POST /api/periodos

​Request body

​Response 201 Created

​Example

​GET /api/periodos/

​Path parameters

​Response 200 OK

​Example

​PUT /api/periodos/

​Path parameters

​Request body

​Response 200 OK

​Example — full update

​Example — status-only update

​DELETE /api/periodos/

​Path parameters

​Response 200 OK

​Example

​PATCH /api/periodos//activar

​Path parameters

​Response 200 OK

​Example

Build docs developers (and LLMs) love

GET /api/periodos

Response `200 OK`

Example

GET /api/periodos/activo

Response `200 OK`

Error `404 Not Found`

Example

POST /api/periodos

Request body

Response `201 Created`

Example

GET /api/periodos/

Path parameters

Response `200 OK`

Example

PUT /api/periodos/

Path parameters

Request body

Response `200 OK`

Example — full update

Example — status-only update

DELETE /api/periodos/

Path parameters

Response `200 OK`

Example

PATCH /api/periodos//activar

Path parameters

Response `200 OK`

Example