> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solvice.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Request Schema

> Complete Fill API request structure and field reference

The Fill API request defines employees, shifts, and constraints for workforce scheduling optimization.

## Request Structure

```json theme={null}
{
  "employees": [...],      // Required: Available workforce
  "shifts": [...],         // Required: Shifts to fill
  "rules": [...],          // Optional: Labor constraints
  "requirements": [...],   // Optional: Skill requirements
  "fairnessBuckets": [...],// Optional: Workload distribution
  "rests": [...],          // Optional: Rest periods
  "patterns": [...],       // Optional: Shift sequences
  "demands": [...],        // Optional: Coverage requirements
  "assignments": [...],    // Optional: Pre-assigned shifts
  "options": {...},        // Optional: Solver configuration
  "weights": {...},        // Optional: Constraint weights
  "hook": "..."            // Optional: Webhook URL
}
```

## Top-Level Fields

<ParamField body="shifts" type="array" required>
  List of shifts to be filled with employees. See [Shift](#shift).
</ParamField>

<ParamField body="employees" type="array" required>
  List of available employees. See [Employee](#employee).
</ParamField>

<ParamField body="rules" type="array">
  Labor rules and constraints. See [Rule](#rule).
</ParamField>

<ParamField body="requirements" type="array">
  Skill requirements across shifts. See [Requirement](#requirement).
</ParamField>

<ParamField body="fairnessBuckets" type="array">
  Workload distribution groups. See [FairnessBucket](#fairnessbucket).
</ParamField>

<ParamField body="rests" type="array">
  Rest period constraints. See [Rest](#rest).
</ParamField>

<ParamField body="patterns" type="array">
  Shift sequence patterns. See [Pattern](#pattern).
</ParamField>

<ParamField body="demands" type="array">
  Coverage requirements. See [Demand](#demand).
</ParamField>

<ParamField body="assignments" type="array">
  Pre-assigned employee-shift pairs. See [Assignment](#assignment).
</ParamField>

<ParamField body="options" type="object">
  Solver configuration. See [Options](#options).
</ParamField>

<ParamField body="weights" type="object">
  Custom constraint weights. See [Weights](#weights).
</ParamField>

<ParamField body="hook" type="string (URI)">
  Webhook URL for completion notification.
</ParamField>

***

## Shift

Shifts represent time slots that need employees assigned.

```json theme={null}
{
  "name": "morning-kitchen",
  "from": "2024-04-18T08:00:00",
  "to": "2024-04-18T14:00:00",
  "skills": [{ "name": "kitchen" }],
  "min": 1,
  "max": 2,
  "priority": 1,
  "tags": [{ "name": "EARLY" }],
  "blocklist": ["employee-3"],
  "cost": 50
}
```

<ParamField body="name" type="string" required>
  Unique identifier for the shift.
</ParamField>

<ParamField body="from" type="datetime" required>
  Shift start time (ISO 8601 format).
</ParamField>

<ParamField body="to" type="datetime" required>
  Shift end time (ISO 8601 format).
</ParamField>

<ParamField body="skills" type="array">
  Required skill references. Employees must have matching skills.
</ParamField>

<ParamField body="min" type="integer" default="1">
  Minimum employees required for this shift.
</ParamField>

<ParamField body="max" type="integer" default="1">
  Maximum employees allowed for this shift.
</ParamField>

<ParamField body="priority" type="integer (1-10)">
  Shift importance. `1` = highest priority, `10` = lowest.
</ParamField>

<ParamField body="tags" type="array">
  Shift tags for grouping in rules and patterns. See [ShiftTag](#shifttag).
</ParamField>

<ParamField body="blocklist" type="array">
  Employee names that cannot be assigned to this shift.
</ParamField>

<ParamField body="cost" type="number">
  Financial cost for assigning this shift. Minimized in partial planning.
</ParamField>

<ParamField body="rests" type="array">
  Rest requirements after this shift. See [ShiftRest](#shiftrest).
</ParamField>

### ShiftTag

```json theme={null}
{ "name": "NIGHT" }
```

<ParamField body="name" type="string" required>
  Tag identifier used in rules and patterns.
</ParamField>

***

## Employee

Employees are the workforce available for shift assignments.

```json theme={null}
{
  "name": "Alice",
  "skills": [{ "name": "kitchen", "level": 3 }],
  "availability": ["2024-04-18T08:00:00/2024-04-18T18:00:00"],
  "preference": ["morning-kitchen"],
  "lastRestDate": "2024-04-17"
}
```

<ParamField body="name" type="string" required>
  Unique identifier for the employee.
</ParamField>

<ParamField body="skills" type="array">
  Employee capabilities with optional proficiency levels.
</ParamField>

<ParamField body="availability" type="array">
  Available time ranges (ISO 8601 interval format).
</ParamField>

<ParamField body="preference" type="array">
  Preferred shift names.
</ParamField>

<ParamField body="lastRestDate" type="date">
  Last rest date before the planning period.
</ParamField>

***

## Rule

Rules define labor constraints using counters or sequences.

```json theme={null}
{
  "constraint": "COUNTER",
  "type": "WORKING_DAYS",
  "min": 2,
  "max": 5,
  "period": {
    "from": "2024-04-01",
    "to": "2024-04-07"
  },
  "shifts": ["NIGHT"],
  "then": { ... }
}
```

<ParamField body="constraint" type="string" required>
  Rule type: `COUNTER` or `SEQUENCE`.
</ParamField>

<ParamField body="type" type="string" required>
  What to measure: `DAYS_WORKED`, `DAYS_IDLE`, `WEEKENDS_WORKED`, `WEEKENDS_IDLE`, `SHIFT_TYPES_WORKED`, `SHIFT_TYPES_HOURS_WORKED`, `HOURS_WORKED`.
</ParamField>

<ParamField body="min" type="integer">
  Minimum count or sequence length.
</ParamField>

<ParamField body="max" type="integer">
  Maximum count or sequence length.
</ParamField>

<ParamField body="period" type="object">
  Time scope with `from`/`to` or rolling `duration`.
</ParamField>

<ParamField body="shifts" type="array">
  Filter to specific shift tags.
</ParamField>

<ParamField body="then" type="Rule">
  Conditional rule triggered when threshold exceeded.
</ParamField>

***

## Requirement

Skill requirements across multiple shifts.

```json theme={null}
{
  "shifts": ["shift-1", "shift-2"],
  "skill": "supervisor",
  "value": 1
}
```

<ParamField body="shifts" type="array" required>
  Shift names this requirement applies to.
</ParamField>

<ParamField body="skill" type="string" required>
  Required skill name.
</ParamField>

<ParamField body="value" type="integer" required>
  Number of employees with this skill required.
</ParamField>

***

## FairnessBucket

Groups for equitable workload distribution.

```json theme={null}
{
  "employees": ["Alice", "Bob"],
  "shifts": ["shift-1", "shift-2"],
  "period": { "from": "2024-01-01", "to": "2024-01-07" },
  "target": "PT40H"
}
```

<ParamField body="employees" type="array" required>
  Employees in this fairness group.
</ParamField>

<ParamField body="shifts" type="array" required>
  Shifts to distribute fairly.
</ParamField>

<ParamField body="period" type="object">
  Evaluation period with `from` and `to` dates.
</ParamField>

<ParamField body="target" type="string (ISO 8601 duration)" required>
  Target workload per employee.
</ParamField>

***

## Pattern

Shift sequence preferences or restrictions.

```json theme={null}
{
  "type": "MULTI_DAY",
  "satisfy": "PROHIBITED",
  "elements": [
    { "type": "ON", "tags": ["LATE"] },
    { "type": "ON", "tags": ["EARLY"] }
  ],
  "weight": 5
}
```

<ParamField body="type" type="string" required>
  `SINGLE_DAY` or `MULTI_DAY`.
</ParamField>

<ParamField body="satisfy" type="string" required>
  `PREFERRED`, `UNPREFERRED`, or `PROHIBITED`.
</ParamField>

<ParamField body="elements" type="array">
  Sequence elements with `type` (`ON`/`OFF`) and `tags` (tag list).
</ParamField>

<ParamField body="weight" type="integer">
  Priority weight for preferred patterns.
</ParamField>

***

## Demand

Coverage requirements independent of shifts.

```json theme={null}
{
  "name": "peak-hours",
  "from": "2024-01-01T14:00:00",
  "to": "2024-01-01T18:00:00",
  "skills": [{ "name": "general" }],
  "min": 3,
  "max": 5
}
```

<ParamField body="name" type="string" required>
  Unique demand identifier.
</ParamField>

<ParamField body="from" type="datetime" required>
  Demand period start.
</ParamField>

<ParamField body="to" type="datetime" required>
  Demand period end.
</ParamField>

<ParamField body="skills" type="array" required>
  Required skills for this demand period.
</ParamField>

<ParamField body="min" type="integer">
  Minimum employees required.
</ParamField>

<ParamField body="max" type="integer">
  Maximum employees allowed.
</ParamField>

***

## Assignment

Pre-defined employee-shift pairings.

```json theme={null}
{
  "shift": "morning-1",
  "employee": "Alice",
  "locked": true
}
```

<ParamField body="shift" type="string" required>
  Shift name to assign.
</ParamField>

<ParamField body="employee" type="string" required>
  Employee name to assign.
</ParamField>

<ParamField body="locked" type="boolean" default="false">
  If `true`, the solver cannot change this assignment.
</ParamField>

***

## Options

Solver configuration settings.

```json theme={null}
{
  "hardAvailability": true,
  "hardSkill": true,
  "partialPlanning": false,
  "explanation": { "enabled": true },
  "idleWeekend": { ... }
}
```

<ParamField body="hardAvailability" type="boolean" default="true">
  Enforce availability as hard constraint.
</ParamField>

<ParamField body="hardSkill" type="boolean" default="true">
  Enforce skill matching as hard constraint.
</ParamField>

<ParamField body="hardBlacklist" type="boolean" default="true">
  Enforce blocklist as hard constraint.
</ParamField>

<ParamField body="partialPlanning" type="boolean" default="false">
  Allow unfilled shifts in solution.
</ParamField>

<ParamField body="penaliseZeroHours" type="boolean">
  Penalize employees with no assignments.
</ParamField>

<ParamField body="explanation" type="object">
  Explanation settings. See [ExplanationOptions](#explanationoptions).
</ParamField>

<ParamField body="idleWeekend" type="object">
  Weekend definition. See [IdleWeekendDefinition](#idleweekenddefinition).
</ParamField>

### ExplanationOptions

```json theme={null}
{ "enabled": true, "filterHardConstraints": false }
```

<ParamField body="enabled" type="boolean" default="false">
  Enable alternative generation.
</ParamField>

<ParamField body="filterHardConstraints" type="boolean" default="false">
  Exclude infeasible alternatives from response.
</ParamField>

### IdleWeekendDefinition

```json theme={null}
{
  "fromDayOfWeek": "FRIDAY",
  "fromTime": "19:00:00",
  "toDayOfWeek": "SUNDAY",
  "toTime": "23:00:00",
  "restTime": "PT36H"
}
```

<ParamField body="fromDayOfWeek" type="string" required>
  Weekend start day.
</ParamField>

<ParamField body="fromTime" type="string" required>
  Weekend start time (HH:mm:ss).
</ParamField>

<ParamField body="toDayOfWeek" type="string" required>
  Weekend end day.
</ParamField>

<ParamField body="toTime" type="string" required>
  Weekend end time (HH:mm:ss).
</ParamField>

<ParamField body="restTime" type="string (ISO 8601 duration)">
  Minimum consecutive rest for idle weekend.
</ParamField>

***

## Rest

Rest period constraints.

```json theme={null}
{
  "tags": ["NIGHT"],
  "sequence": "AFTER",
  "min": "PT11H",
  "minConsecutive": "PT8H"
}
```

<ParamField body="tags" type="array">
  Shift tags that trigger this rest.
</ParamField>

<ParamField body="excludes" type="array">
  Shift tags excluded from rest calculation.
</ParamField>

<ParamField body="sequence" type="string">
  `AFTER` or `BEFORE` the triggering shift.
</ParamField>

<ParamField body="period" type="object">
  Fixed period for periodic rest rules.
</ParamField>

<ParamField body="periodType" type="string">
  Rolling period: `WEEKLY`, `DAILY`.
</ParamField>

<ParamField body="min" type="string (ISO 8601 duration)">
  Minimum total rest.
</ParamField>

<ParamField body="minConsecutive" type="string (ISO 8601 duration)">
  Minimum uninterrupted rest.
</ParamField>

<ParamField body="frequency" type="integer">
  Maximum rest occurrences.
</ParamField>