API Reference

Technical documentation and endpoint specifications

API Base URL

https://api.planifica.education

All API endpoints are relative to this base URL. For example, to optimize a schedule, POST to https://api.planifica.education/api/v1/edt/optimize

Authentication

All API requests require authentication using an API key. Include your API key in the request header.

Authorization Header

Authorization: Bearer YOUR_API_KEY

Security Note

Keep your API key secure and never expose it in client-side code. Use environment variables in production.

API Endpoints

POSThttps://api.planifica.education/api/v1/edt/optimize

Start an asynchronous optimization task

Request Body

{
  "requestid": "unique-request-identifier",
  "config": {
    "max_time_in_seconds": 600,
    "objective_type": "AFFINITY",
    "use_objective": false,
    "max_solutions": 1,
    "debug_enabled": true,
    "debug_level": "full"
  },
  "timetable": {
    "working_days": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
    "holidays": ["2024-12-25"],
    "time_granularity": 30,
    "num_weeks": 1
  },
  "subjects": [
    {
      "code": "AR",
      "name": "Arabe"
    },
    {
      "code": "MA", 
      "name": "Mathematics"
    }
  ],
  "grades": [
    {
      "code": "CP",
      "groups": ["A", "B"],
      "working_hours": [
        ["Monday", {
          "available_hours": [["08:00", "12:00"], ["13:00", "17:00"]],
          "unavailable_periods": [["10:00", "10:30"]]
        }]
      ]
    }
  ],
  "classrooms": [
    {
      "id": 1,
      "subjects": ["AR", "MA"]
    }
  ],
  "instructors": [
    {
      "id": 1,
      "name": "John Doe",
      "subjects": ["MA"],
      "capacity": 24,
      "grades": ["CP"],
      "available_days": [
        ["Monday", {
          "available_hours": [["08:00", "17:00"]],
          "unavailable_periods": [["12:00", "13:00"]]
        }]
      ]
    }
  ],
  "schemas": [
    {
      "grade": "CP",
      "sessions": [
        {
          "id": "session_1",
          "session": "MATH_001",
          "grade": "CP",
          "group": "A",
          "duration": 2,
          "subject": "MA"
        },
        {
          "id": "session_2", 
          "session": "MATH_002",
          "grade": "CP",
          "group": "B",
          "duration": 2,
          "subject": "MA"
        }
      ]
    }
  ]
}

Response

{
  "id": "task_123456",
  "status": "queued",
  "message": "Optimization task queued successfully"
}

Optimization Configuration

Control optimization behavior with intelligent stop conditions that balance solution quality, processing time, and resource consumption.

Configuration Guidelines

• Use shorter time limits (60-300s) for interactive applications
• Set max_solutions to null for quality-focused optimization
• Enable no_improvement_timeout for resource conservation
• Always enable use_objective for better solution quality

Time-Based

Set hard limits on processing time to ensure responsive applications.

max_time_in_seconds: 300

Solution-Based

Control how many solutions to explore for comparison or quick results.

max_solutions: null

Quality-Based

Stop automatically when solution quality stops improving.

no_improvement_timeout_seconds: 60

Error Codes

The API returns specific error codes to help identify and resolve scheduling issues. Each error includes a code, description, and suggested resolution.

Session Scheduling Errors

UNSCHEDULABLE_SESSIONScheduling

A session cannot be scheduled due to general constraints

Common causes: Multiple conflicting constraints preventing session placement

NO_VALID_SESSIONSConfiguration

No valid sessions are available for scheduling

Common causes: All sessions have been filtered out due to constraints

Resource Availability Errors

NO_AVAILABLE_TIMESLOTSAvailability

No time slots are available for the session

Common causes: All time slots are occupied or outside working hours

NO_AVAILABLE_ROOMSAvailability

No classrooms are available for the session

Common causes: All rooms are occupied or don't meet session requirements

NO_AVAILABLE_INSTRUCTORSAvailability

No instructors are available for the session

Common causes: All instructors are busy or don't teach the subject

NO_CLASSROOMSConfiguration

No classrooms exist in the system

Common causes: Missing classroom data or configuration

NO_INSTRUCTORSConfiguration

No instructors exist in the system

Common causes: Missing instructor data or configuration

Capacity Errors

NO_AVAILABLE_CAPACITYCapacity

Insufficient capacity available for the session

Common causes: Room capacity is smaller than required student count

INSUFFICIENT_INSTRUCTOR_CAPACITYCapacity

Instructor doesn't have enough capacity for the session

Common causes: Instructor workload limits exceeded

INSUFFICIENT_TOTAL_CAPACITYCapacity

Total system capacity is insufficient

Common causes: Overall resource shortage

INSTRUCTOR_OVERALLOCATIONCapacity

Instructor is assigned beyond their availability

Common causes: Double-booking or exceeding work limits

Conflict Errors

INSTRUCTOR_TIME_CONFLICTConflict

Instructor has a scheduling conflict

Common causes: Instructor assigned to multiple sessions at the same time

ROOM_TIME_CONFLICTConflict

Room has a scheduling conflict

Common causes: Room assigned to multiple sessions at the same time

GRADE_GROUP_TIME_CONFLICTConflict

Grade group has a scheduling conflict

Common causes: Students assigned to multiple sessions at the same time

DUPLICATE_SESSION_IDConflict

Multiple sessions share the same identifier

Common causes: Data import error or ID generation issue

Data Integrity Errors

INVALID_WORKING_DAYValidation

Session scheduled outside valid working days

Common causes: Session assigned to weekend or holiday

INSTRUCTOR_NO_GRADESConfiguration

Instructor is not assigned to any grades

Common causes: Missing grade assignment data for instructor

Locked Session Errors

LOCKED_SESSION_INSTRUCTOR_UNAVAILABLEAvailability

A locked session cannot be scheduled because the assigned instructor is unavailable at the locked time

Common causes: Instructor is busy with another session or outside their availability hours

LOCKED_SESSION_OUTSIDE_GRADE_HOURSScheduling

A locked session is scheduled outside the grade's defined working hours

Common causes: Session time conflicts with grade's available hours or break periods

Error Response Example

{
  "id": "validation_123",
  "valid": false,
  "errors": [
    {
      "message": "Session scheduled outside valid working days",
      "code": "INVALID_WORKING_DAY",
      "grade": "CP",
      "group": "A",
      "subject": "MATH"
    },
    {
      "message": "No instructors are available for the session",
      "code": "NO_AVAILABLE_INSTRUCTORS",
      "grade": "CM1",
      "subject": "SCIENCE"
    }
  ],
  "warnings": []
}

Error Handling

HTTP Status Codes

200

Success

Request completed successfully

400

Bad Request

Invalid request data or missing required fields

401

Unauthorized

Missing or invalid API key

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Unexpected server error

Error Response Format

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Missing required field: timetable.working_days",
    "details": {
      "field": "timetable.working_days",
      "expected": "array",
      "received": "undefined"
    }
  }
}

Rate Limits

Current Rate Limits

• 100 requests per minute for optimization endpoints
• 1000 requests per minute for status and validation endpoints
• 10 concurrent optimization tasks per API key

Rate limit information is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1640995200