API reference

Base URL https://api.operex.eu · contract version v1. Send your key as Authorization: Bearer <key>.

Field, enum and symbol names are the contract and stay English in every locale; only prose is localized. Schemas track the shipping engine (apps/shift-engine).

⬇ OpenAPI spec (JSON)OpenAPI specification ↓

Endpoints

Authentication

Every request carries an API key as a bearer token: Authorization: Bearer <key>. Keys are per-account and can be rotated. GET /health needs no key.

POST /v1/schedule:build

Builds one month for a site and, when evaluate is true, runs the compliance evaluator.

POST /v1/schedule:build
Authorization: Bearer sk_…
Content-Type: application/json

{
  "site": {
    "site_id": "plant-01",
    "shift_pattern_key": "12h-2-2-4",
    "anchor": "2022-08-09",
    "n_crews": 4,
    "dayworker_anchor": "2022-08-08",
    "min_headcount": { "safety_total": 8 },
    "employees": [
      { "staff_id": "1000001", "name": "…", "role": "Operator", "kind": "shift", "crew": 0 },
      { "staff_id": "9000001", "name": "…", "role": "Engineer", "kind": "dayworker" }
    ]
  },
  "year": 2025,
  "month": 12,
  "evaluate": true
}

Request — top level

Site

Employee

MinHeadcount

Response

{
  "engine_version": "0.6.2",
  "schedule": {
    "site_id": "plant-01", "year": 2025, "month": 12,
    "days": [ "2025-12-01", … ],
    "rows": { "1000001": [ "É","É","-","-", … ], "9000001": [ "N","N", …, "Üp","Üp" ] },
    "coverage": [ { "day": "2025-12-01", "morning": 1, "afternoon": 0, "night": 1, "dayworker": 1, "understaffed": [] }, … ],
    "statistics": { "1000001": { "worked_hours": 192, "night_count": 8, "shift_count": 16, "vacation_days": 0, "flex_days": 0, "holiday_rest_days": 0, "expected_hours": 176, "balance": 16 }, … }
  },
  "compliance": {
    "rulebook_version": "2026-09-03-draft",
    "violations": [],
    "notes": [ "This report signals and justifies; it does not guarantee compliance. …" ],
    "any_needs_review": false
  }
}

Top level: engine_version, schedule, and compliance (null when evaluate is false).

schedule

coverage[]

statistics (PersonStats)

POST /v1/schedule:build-range

Same as POST /v1/schedule:build, but over an arbitrary inclusive date range instead of one calendar month — one call for a fortnight, a quarter or a full year. The rotation, holidays, rule_overrides and per-cell assignments behave identically; compliance rolling windows span the whole range, and statistics aggregate over the span. schedule is a RangeSchedule: the same shape as schedule but anchored by start and end instead of year and month.

Request — top level

Shift symbols

Each cell in rows is one symbol:

Worker kinds

Compliance report

When evaluate is true, compliance holds the findings. It signals and justifies; it does not guarantee compliance. Each violation cites its statute section; findings from a draft rule carry needs_review: true. Rules checked: daily rest, daily and weekly maximum hours, night-work limit, weekly rest day.

violation

GET /v1/patterns

Lists the available shift patterns: key, name, hours, cycle_length. Use a key as shift_pattern_key or dayworker_pattern_key.

GET /v1/holidays?year=

Returns the base national public holidays for a year (fixed dates + Easter-derived movable feasts). This is the seed data an editor shows: override it (rename, add, remove) and pass the effective set back in the build request’s holidays field. The engine only computes the default set; it never stores edits.

GET /v1/rules

Returns the base compliance rules with their editable thresholds. This is the seed data a legal-compliance editor shows: adjust the numeric thresholds (min rest hours, max hours…) and the on/off flag, then pass the deltas back in the build request’s rule_overrides field. Which rules exist and their statute references are engine-owned and not editable.

GET /v1/version

Returns the engine and rule-data versions. Pin these to reproduce a roster.

{
  "engine_version": "0.6.2",
  "pattern_library_version": "2026-08-28",
  "rulebook_version": "2026-09-03-draft",
  "shift_times_version": "2026-08-28"
}

Determinism, timezones & versioning

The same request plus the same engine_version and rulebook_version always returns the same roster. The rotation is a pure function of the date relative to the site’s anchor; there is no hidden state and no randomness. Worked hours are timezone-aware (the site’s IANA zone, Europe/Budapest by default): a night shift spanning a daylight-saving change is measured as its true 11h (spring) or 13h (autumn), and the autumn 13h night trips the daily-hours rule. Rule data (patterns, shift times, holidays, the labour-law rulebook) is versioned and overridable per request, so a schedule can be reproduced and audited later.

Errors

OpenAPI specification

The full machine-readable contract is served at /engine/shift-scheduling/openapi.json (OpenAPI 3.1). The hosted engine also exposes it at /openapi.json with interactive docs at /docs.

/engine/shift-scheduling/openapi.json ↗