API Reference

Authentication

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

X-API-Key: digi_xxxxxxxxxxxxxxxxxxxxxxxx
Authorization: ApiKey digi_xxxxxxxxxxxxxxxxxxxxxxxx

School Identifier (Required)

In addition to your API key, every optimize, allocation, and validate request must include schoolExternalId and schoolNameas top-level fields identifying which school the request is for. This is enforced server-side — requests without them are rejected.

{
  "schoolExternalId": "your-school-id",
  "schoolName": "School Display Name"
}

API Endpoints

{
  "schoolExternalId": "your-school-id",
  "schoolName": "School Display Name",
  "requestid": "unique-request-identifier",
  "config": {
    "max_time_in_seconds": 600,
    "objective_type": "AFFINITY",
    "use_objective": false,
    "debug_enabled": true,
    "debug_level": "full"
  },
  "data": {
    "requestid": "unique-request-identifier",
    "config": {
      "max_time_in_seconds": 600,
      "objective_type": "AFFINITY",
      "use_objective": false,
      "debug_enabled": true,
      "debug_level": "full"
    },
    {
      "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"
        }
      ]
    }
  ]
}

{
  "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.

Data Models

Key objects used across the optimization, allocation, and validation endpoints.

{
  "schoolExternalId": "your-school-id",
  "schoolName": "School Display Name"
}

Partner API

The endpoints above belong to a dedicated gateway for managed partner integrations: validate a payload, submit an optimization or allocation job, and poll the task by ID. Authentication and request shape are the same as described in Authentication above.

Gateway Endpoints

Task Status Values

Migration Guide: Direct ML Backend → Partner Gateway

If you previously integrated directly against the optimization engine (without an API key, on a different host), use this section to move onto the partner gateway above. Two independent things change: where and how you call it, and what you send— the request schema itself has breaking changes versus an older combined-config shape some direct integrations still use.

What's Changing

Required Fields

Add schoolExternalId and schoolName as top-level siblings of your existing request — there is no wrapper object. See Authentication above for the exact shape and validation rules.

Breaking Schema Change: Combined Subject Config Removed

The old combined subject config (one object per subject mixing capacity, affinity, cardinality, and a single-day window) is not deprecated — it has been removed entirely. There is no combined model in the backend anymore; only the three split configs below exist.

{
  "subject": "math",
  "capacity": 30,
  "affinity": 5,
  "cardinality": 2,
  "day": "monday",
  "start": "08:00",
  "end": "12:00"
}

// schemas[].capacity_configs
{
  "subject": "math",
  "capacity": 30,
  "start_day": "monday",
  "start_time": "08:00",
  "end_day": "monday",
  "end_time": "12:00"
}
// affinity_configs / cardinality_configs
// follow the same start_day/start_time/
// end_day/end_time shape

• Each schemas[] entry (one per grade) now carries separate arrays: capacity_configs, affinity_configs, cardinality_configs — instead of one combined object per subject.
• Field rename: day / start / end → start_day / start_time / end_day / end_time. The window can now span multiple days.
• New optional array ordering_configs — session-ordering constraints (follows / avoid_after / distance_between) between two subjects, with min_gap_slots / max_gap_slots. Omit it if you don't need ordering constraints.
• classrooms[] gained an optional specialized: boolean (default false) to mark scarce/specialized rooms (labs, gyms) for capacity-aware scheduling.

New error codes you may see from stricter validation and the features above: SESSION_ORDERING_CYCLE, DISTANCE_BETWEEN_INFEASIBLE, INVALID_DISTANCE_BETWEEN_CONFIG, SPECIALIZED_ROOM_CAPACITY_EXCEEDED, INSUFFICIENT_CONTINUOUS_SLOTS, among others — see Error Codes below.

Response & Polling Changes

• Task IDs: optimize and allocation responses include a taskId generated by the gateway. Use this taskId — not any internal id in the response body — for all follow-up status, solutions, and cancel calls.
• Status normalization: task status is normalized to PENDING / PROCESSING / COMPLETED / FAILED (see Task Status Values above).
• Stats relocation: if you previously read top-level stats on an allocation response, stats now live per solution: allocations.solutions[].stats.

Migration Checklist

1. Create an API key (see Authentication); store it securely — it's shown once.
2. Add schoolExternalId and schoolName as top-level sibling fields on every request.
3. If still on the old combined subject config: split it into capacity_configs, affinity_configs, cardinality_configs under each schemas[] entry.
4. Rename day / start / end to start_day / start_time / end_day / end_time on every config window.
5. Remove any non-schema fields from schemas[].sessions[] objects (strictly validated).
6. Switch the request host to api.planifica.education and confirm paths match /api/v1/edt/* (note /allocate → /allocation if applicable).
7. Add the Authorization: ApiKey <key> (or X-API-Key) header to every request.
8. Update polling logic to use the gateway's taskId from the initial response, not any internal id.
9. Update response parsing for the relocated per-solution stats and the normalized status enum.
10. Re-test validate, optimize, and allocation end-to-end against the new host before cutting over production traffic.

Side-by-Side Example

POST /api/v1/edt/optimize
Content-Type: application/json

{
  "requestid": "req-001",
  "timetable": { "time_granularity": 30 },
  "schemas": [{
    "grade": "G1",
    "sessions": [],
    "teachers_capacities": [{
      "subject": "math", "capacity": 30,
      "affinity": 5, "cardinality": 2,
      "day": "monday",
      "start": "08:00", "end": "12:00"
    }]
  }]
}

POST /api/v1/edt/optimize
Content-Type: application/json
Authorization: ApiKey digi_xxxxxxxxxxxxxxxxxxxx

{
  "schoolExternalId": "school-abc-001",
  "schoolName": "ABC High School",
  "requestid": "req-001",
  "timetable": { "time_granularity": 30 },
  "schemas": [{
    "grade": "G1",
    "sessions": [],
    "capacity_configs": [{ "subject": "math", "capacity": 30,
      "start_day": "monday", "start_time": "08:00",
      "end_day": "monday", "end_time": "12:00" }],
    "affinity_configs": [{ "subject": "math", "affinity": 5,
      "start_day": "monday", "start_time": "08:00",
      "end_day": "monday", "end_time": "12:00" }],
    "cardinality_configs": [{ "subject": "math", "cardinality": 2,
      "start_day": "monday", "start_time": "08:00",
      "end_day": "monday", "end_time": "12:00" }]
  }]
}

Error Codes

The API returns specific error codes to help identify and resolve scheduling issues. Each errors[]/warnings[] entry has a stable code you should branch on, plus a human-readable message that's safe to show end users but may be reworded between releases.

Error Handling

{
  "statusCode": 422,
  "timestamp": "2026-07-08T10:15:00.000Z",
  "path": "/api/v1/edt/optimize",
  "method": "POST",
  "message": ["Input should be a valid integer"],
  "requestId": "b4d6e6b0-6e0a-4b3a-9a3a-1c9b9a3f2e11",
  "code": "OPTIMIZER_ERROR_422",
  "details": [
    {
      "field": "sessions.3.duration",
      "message": "Input should be a valid integer",
      "type": "int_parsing"
    }
  ]
}

Rate Limits

Rate limit information is included in response headers:

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