API Documentation

When submitting a schedule for solving, you're asking our AI to assign employees to shifts while respecting constraints and preferences. This guide explains the structure of that request.

Request structure

A schedule submission contains six required fields:

{
  "employees": [],
  "shifts": [],
  "spots": [],
  "settings": {},
  "callbackUrl": "https://api.yourdomain.com/solver-callback",
  "callbackAuthenticationHeaderName": "X-API-Key",
  "callbackAuthenticationHeaderValue": "your-secret-key"
}

Additionally, you can optionally specify:

{
  "numberOfAllowedShiftCollisions": 0
}

Core collections

Employees

The people available for scheduling. Each employee has skills, team memberships, contract rules, and preferences. See Employees in your schedule for details.

Shifts

The work periods that need to be filled. Each shift specifies when it occurs, which spot it's for, whether it's mandatory or optional, and can include employee preferences. See Shifts in your schedule for details.

Spots

Locations or roles where work happens (e.g., "Emergency Room", "Reception Desk"). Spots have skill and team requirements that constrain which employees can work there. See Spots in your schedule for details.

Solver configuration

Settings

Fine-tune how the solver weighs different constraints. Want to prioritize employee preferences over even shift distribution? Adjust the weights. See Settings in your request for the full list of configurable constraints.

Callback

The solver processes schedules asynchronously. When complete, it POSTs the solution to your callbackUrl. Use the authentication header fields to secure this callback-the solver will include your specified header in the callback request.

Your callback endpoint should:

  • Accept POST requests with JSON payloads
  • Return 200 OK promptly (process the solution asynchronously if needed)
  • Handle authentication using the header you specified

If your callback fails, the solver will not retry. You can retrieve results later via GET /api/v1/{id}.

Next steps