---
title: "Submit Schedule"
method: POST
path: "/submit"
---

# Submit Schedule

`POST /submit`

Create an API generation session for a validated combined configuration.

Args:
    request: Pydantic-validated combined scheduler configuration from the body.

Returns:
    A new session identifier and its base schedule endpoint.

Raises:
    HTTPException: Status 429 when active-session capacity is full; status 422
        for course, schedule, or candidate-slot limits; status 500 if work cannot
        be submitted; or status 400 for other request setup failures.

Behavior:
    Expired sessions and all built-in request limits are checked before work is
    accepted. Scheduler construction is queued on the shared executor with the
    API solver timeout. A UUID-backed session is registered immediately with
    empty results so later requests can await initialization asynchronously.

## Request body

- CombinedConfig — Represents a combined configuration. **Usage:** ```python CombinedConfig(config=..., time_slot_config=..., limit=10) ```
  - `config` SchedulerConfigInput, required — Represents a scheduler configuration. **Usage:** ```python SchedulerConfig(rooms=[...], labs=[...], courses=[...], faculty=[...]) ```
    - `rooms` Room[], required — List of available room names
    - `labs` Lab[], required — List of available lab names
    - `courses` CourseConfigInput[], required — List of course configurations
      - `course_id` string, required — Course name
      - `credits` integer, required — Number of credit hours
      - `room` Room[], required — List of acceptable room names
      - `lab` Lab[] — List of acceptable lab names
      - `conflicts` Course[], required — List of course IDs that cannot be scheduled simultaneously
      - `faculty` Faculty[], nullable, required — Faculty candidates, or null to derive candidates from faculty course preferences
    - `faculty` FacultyConfigInput[], required — List of faculty configurations
      - `name` string, required — Faculty name
      - `maximum_credits` integer, required — Maximum credit hours they can teach
      - `maximum_days` integer — Maximum number of days they are willing to teach (0-5, optional)
      - `minimum_credits` integer, required — Minimum credit hours they must teach
      - `unique_course_limit` integer, required — Maximum number of different courses they can teach
      - `times` object, required — Dictionary mapping day names to time ranges
      - `course_preferences` object — Dictionary mapping course IDs to preference scores
      - `room_preferences` object — Dictionary mapping room IDs to preference scores
      - `lab_preferences` object — Dictionary mapping lab IDs to preference scores
      - `mandatory_days` Day[] — Set of days the faculty must teach on
  - `time_slot_config` TimeSlotConfigInput, required — Represents a time slot configuration. **Usage:** ```python TimeSlotConfig(times={...}, classes=[...]) ```
    - `times` object, required — Dictionary mapping day names to time blocks
    - `classes` ClassPattern[], required — List of class patterns
      - `credits` integer, required — Number of credit hours
      - `meetings` Meeting[], required — List of meeting times
        - `day` 'MON' | 'TUE' | 'WED' | 'THU' | 'FRI', required — Day of the week
        - `start_time` string — Time in HH:MM format
        - `duration` integer, required — Duration of the meeting in minutes
        - `lab` boolean — Whether the meeting is in a lab
      - `disabled` boolean — Whether the pattern is disabled
      - `start_time` string — Time in HH:MM format
    - `max_time_gap` integer — Maximum time gap between time slots to determine if they are adjacent
    - `min_time_overlap` integer — Minimum overlap between time slots
  - `limit` integer — Maximum number of schedules to generate
  - `optimizer_flags` OptimizerFlags[] — List of optimizer flags

## Response `200`

Successful Response

- SubmitResponse — Response model for schedule submission requests. **Usage:** ```python SubmitResponse(schedule_id="...", endpoint="/schedules/...") ``` **Fields:** - schedule_id: Unique identifier for the generated schedule session - endpoint: URL endpoint to access the schedule
  - `schedule_id` string, required
  - `endpoint` string, required

## Other responses

- `422` — Validation Error

## Changes

- **2026-07-19** `56f0e753f2e4` — 1 info
  - request property `config/courses/items/faculty` list-of-types was widened by adding types `null` to media type `application/json`
- **2026-07-19** `a414b25abf70` — 3 breaking, 2 warning, 1 info
  - the `config/courses/items/faculty` request property's minItems was increased to `1`
  - the `config/courses/items/room` request property's minItems was increased to `1`
  - the `config/rooms` request property's minItems was increased to `1`
  - the `config/courses/items/credits` request property's exclusiveMinimum was set to `0.00`
  - …2 more

[Change history](https://skmtc.dev/mucsci/apis/course-scheduler-api/changes/submit/post.md)

---

[API](https://skmtc.dev/mucsci/apis/course-scheduler-api.md) · [All operations](https://skmtc.dev/mucsci/apis/course-scheduler-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mucsci/course-scheduler-api/revisions/56f0e753f2e4/schema)