Skip to content
Docs
Sign in

Schedule API

Read the board, add jobs from your MIS one at a time or in bulk, edit their steps, move and pin steps, place jobs with a preview, post floor events and scans.

For integrators

Scheduling and Station require Production, the Production trial, or Production+. Shop does not include scheduling. See Plans and billing.

The Schedule API does what the Schedule pages do: it reads the board, adds jobs (imposed here or from your own system), changes the plan and a job's steps, and records what happens on the floor, including scans. Use it to feed the Schedule from your MIS or web shop, from a machine's own controller, or to show the queue on another screen. Every endpoint is under your team, at /a/<team_slug>/schedule/api/v1/.

Every call takes the same authentication as the rest of the API: an API key of a team member, or a signed-in session that also sends its CSRF token when it changes data (see authentication).

Ids are numbers. An object of another team is a 404. Every member can read. Changing the setup (machines, hours, routes, ready checks and settings) needs a team administrator (403 for other members); planning endpoints need a planner (see Schedule settings).

Times, revisions and polling#

  • Times are Unix times in seconds (UTC). The board's tz is your team's time zone, for showing them.
  • Revision. The team's schedule has a revision number, rev, that goes up with every change. Every change answers with the new rev.
  • Polling. Send the last rev you have in If-None-Match when you read the board: an unchanged schedule answers 304 Not Modified at once. ?since=<rev> returns only what changed since.
  • Stale changes. A plan change sends the rev it was based on. If the plan changed in between, the answer is 409 with code: "stale" and what changed. Moves are relative ("after step 88"), so you can usually send them again. Every refusal also has detail, a sentence to show people; code is for your code.
BASE="https://app.example.com/a/<team_slug>/schedule/api/v1"   # your team's slug
AUTH="Authorization: Api-Key $API_KEY"

# The board for one day, then poll it (304 while nothing changed)
curl -s "$BASE/board/?from=1790000000&to=1790086400" -H "$AUTH"
curl -s -o /dev/null -w "%{http_code}" "$BASE/board/" -H "$AUTH" -H 'If-None-Match: "214"'

The board#

GET board/ returns the machines, their working time, downtime, jobs and steps in one answer, with short keys:

{
  "rev": 214,
  "now": 1790000000,
  "tz": "Europe/London",
  "resources": [{"id": 1, "name": "Press 1", "kind": "press_offset", "dept": "Print", "state": "running"}],
  "windows": {"1": [[1789970400, 1790002800]]},
  "downtime": [{"id": 5, "r": 1, "kind": "maintenance", "s": 1790010000, "e": 1790013600, "reason": "Blanket wash"}],
  "orders": {"42": {"job": 42, "name": "Postcard A", "customer": "C-102", "due": 1790200000, "prio": 3,
                    "status": "scheduled", "ready": true, "risk": "ok"}},
  "ops": [{"id": 88, "o": 42, "k": "print", "n": "Print", "r": 1, "seq": 3, "s": 1790003600, "e": 1790011200,
           "su": 2400, "st": "ready", "pin": null, "km": true, "preds": [87]}],
  "tray": [43, 44]
}

In ops, r is the machine, seq the place in its queue, s and e the planned start and end, su the makeready in seconds, st the status and km Only this machine. GET today/ gives the phone view's summary per machine, its counts (late, at risk, machines down, ready to place: the board's own counts) and the jobs ready to place, and GET stations/<machine id>/ a station's current step, Up next and Later today.

Jobs#

Call What it does
GET orders/ Jobs, filtered with status, risk, customer or q.
POST orders/ with {"job": 42} Adds imposition job 42 to the tray (409 with no_layout when it has no selected layout); a finished job is added again as a reprint, or refused with 409 finished when you send "reprint": false. {"jobs": "all"} adds every imposed job with a selected layout that was never scheduled.
POST orders/ with {"name": "…"} Adds a job that isn't imposed (201), with reference (your job number), customer, due_at, priority (1 rush to 4 low), quantity ({"pieces": 5000}, or sheets, area_m2, plates, impressions, lin_m), release_at (not before), ready (tick its manual checks), notes, its press setup for batching (inks: a list of spot inks, plate_set, stock, die, coating), and either route (a route id) or steps: [{"capability": "print", "name": "Print", "minutes": 90, "resource": 2}, …]. Sent again with a reference that is already open, it updates that job's details and answers 200; the steps stay.
PATCH orders/<id>/ {"status": "hold", "hold_reason": "…"} holds a job; {"status": "scheduled"} releases it. Also notes, release_at (not before) and route (re-expands the job's steps); a job that isn't imposed also takes name, reference, customer, due_at, priority and quantity (its unstarted steps are timed again), and inks, plate_set, stock, die and coating (an empty value clears it; its unstarted steps get the new changeovers). A job's setup in the answer holds those five.
DELETE orders/<id>/ Deletes the job from the schedule. The imposition job isn't touched.
POST orders/<id>/to-tray/ Takes the job's unstarted steps off the board and puts it back in the tray, with the rev it was based on; answers the job, the new rev and an activity_id you can undo. 409 started when a step is under way.
POST orders/<id>/refresh/ Times the job again from its layout.
POST orders/<id>/steps/ Adds a step: {"capability": "pack", "name": "Box up", "minutes": 20, "resource": 5, "after_step": 88} (or "first": true).
PATCH orders/<id>/steps/<step id>/ Changes a step that hasn't started: name, lag_min (wait after), minutes (its duration by hand; null goes back to the estimate), and its place in the route with after_step or "first": true.
DELETE orders/<id>/steps/<step id>/ Skips a step that hasn't started.
PATCH orders/<id>/checks/<key>/ {"state": "passed"} or "pending", with eta and note, ticks a manual ready check. Planners may also send "waived".

An imposed job's due date, customer and priority belong to the imposition job: change them with the Imposition API.

# A job from your MIS, with its own steps; the same call with the same reference later updates it
curl -s -X POST "$BASE/orders/" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"name": "Postcard A", "reference": "J-1001", "customer": "C-102", "due_at": "2026-10-22T17:00:00Z",
       "quantity": {"pieces": 5000}, "ready": true,
       "steps": [{"capability": "print", "minutes": 90}, {"capability": "cut"}, {"capability": "pack"}]}'

Many jobs at once#

POST orders/import/ takes the same CSV the board's Import jobs dialog takes (see Adding and editing jobs), as {"csv": "<text>"}, as a multipart file, or as {"rows": [{…}, …]} with the CSV's column names as keys. With "dry_run": true (the default) nothing is written: the answer lists every row with its verdict (create, update or error), its problems and warnings. Send "dry_run": false to write: new jobs land in the tray, a row whose reference is already open updates that job, and rows with errors are left alone. The answer then also carries created and updated (job ids) and the new rev. At most 500 rows per call. GET orders/import/template/ returns a CSV template.

curl -s -X POST "$BASE/orders/import/" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"dry_run": false, "rows": [{"reference": "J-1001", "name": "Postcard A", "due": "2026-10-22",
       "quantity": 5000, "unit": "pieces", "steps": "Print 90m > Cut > Pack", "ready": "yes"}]}'

Plan changes#

Call Body
POST operations/<id>/move/ {"resource": 2, "after": 91, "rev": 214} (or before). Answers the new rev and the steps that changed; 409 with stale, cycle or ineligible.
POST operations/<id>/pin/ {"at": 1790020000, "rev": 214}; unpin/ removes it.
POST operations/<id>/keep-machine/ {"value": false, "rev": 214} switches Only this machine.
POST plan/preview/ {"mode": "place", "orders": [42, 43]}, or no orders for everything ready; {"mode": "replan"} re-orders and re-machines everything outside the time fence (Re-plan). Answers a preview_id, a summary and the steps that would change; nothing is saved.
POST plan/apply/ {"preview_id": "…"} applies a preview, or 409 when the plan changed too much since (plan_changed) or the preview is older than 10 minutes (expired).
POST activity/<id>/undo/, POST activity/<id>/redo/ Undoes a change from GET activity/, or redoes an undo. Steps that changed or started since are kept and listed.

Floor events#

POST operations/<id>/events/ records what happened at a machine: start, makeready_done, pause, resume, progress, done, problem, resolve, note, and check, which ticks a manual ready check the way Stock arrived does. Planners can also send reopen (a done step, within 24 hours) and skip (a step that hasn't started).

curl -s -X POST "$BASE/operations/88/events/" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"kind": "done", "client_id": "00000000-0000-0000-0000-000000000000", "qty_good": 2100, "qty_waste": 40}'
  • client_id makes the call safe to repeat: the same id twice records one event (201 the first time, 200 after).
  • at (when it happened) defaults to now; reason is a pause or problem reason (see The station), note any text.
  • resource records a step started on another machine than planned; running_choice (pause or finish) says what to do with the step already running there.
  • An event that doesn't fit the step answers 409 with invalid_transition, or check_pending when a ready check holds it back. A planner can send "override": true to start anyway.

Scans#

POST operations/scan/ turns a scanned code into the floor event it stands for, so a scanner at a machine, a kiosk or your own shop-floor app can start and finish work without knowing the step's id. The code is the QR code on the ticket printed from the job panel (the job's ticket code), the job's reference (the number your own system printed as a barcode), or a typed label (J-1001, M-17, Job 42). resource is the machine it was scanned at.

  • "kind": "lookup" (the default) writes nothing: the answer has the job and its step for that machine (a station row), or next, the job's next step when it belongs to another machine.
  • "kind": "auto" records the next event of that step: start when it is waiting, makeready_done in makeready, done when it is running, resume when paused; a step with a problem or already done is refused with 409. start, done, pause, resume and makeready_done name the event instead.
  • The other fields are the ones of events/: client_id, at, qty_good, qty_waste, reason, note, operator, override. A written event answers like events/, with station when resource was given.
  • An unknown code answers 404 with unknown_code.
curl -s -X POST "$BASE/operations/scan/" -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"code": "J-1001", "resource": 1, "kind": "auto", "client_id": "00000000-0000-0000-0000-000000000000"}'

Setup#

resources/ (with import-equipment/), downtime/, routes/ (with <id>/test/?job=42), checks/ and settings/ create, read, change and delete the machines, downtime, routes, ready checks and settings. A route's steps may carry minutes (a time by hand for new jobs' steps), and "auto_match": false makes it a template that is only used when a job names it. Changes need a team administrator, except that a planner may POST routes/ a template (it is saved with auto_match false and no match), except POST resources/<id>/down/ and up/, which any member can call to report a machine down or back up. PATCH settings/ also takes timezone, the team's time zone (an IANA name such as Europe/London; blank for UTC), the same field as the team settings: the shop hours are re-timed in it.

GET activity/ lists the last 50 plan changes, and GET alerts/ the open alerts (POST alerts/<id>/ack/ acknowledges one).

Every Schedule endpoint#

API operations tagged scheduling
MethodPathWhat it does
GET /a/{team_slug}/schedule/api/v1/activity/ List the latest plan changes and floor decisions, newest first.
POST /a/{team_slug}/schedule/api/v1/activity/{id}/redo/ Redo an undone change (the undo's id).
POST /a/{team_slug}/schedule/api/v1/activity/{id}/undo/ Undo a plan change (steps changed or started since are kept).
GET /a/{team_slug}/schedule/api/v1/alerts/ List the open alerts.
POST /a/{team_slug}/schedule/api/v1/alerts/{id}/ack/ Acknowledge an alert.
GET /a/{team_slug}/schedule/api/v1/board/ Read the planning board: machines, working time, downtime, jobs and steps.
GET /a/{team_slug}/schedule/api/v1/checks/ Read the team's ready checks.
PATCH /a/{team_slug}/schedule/api/v1/checks/ Switch built-in ready checks, set custom checks and Require a proof.
GET /a/{team_slug}/schedule/api/v1/downtime/ List downtime and overtime (open and coming).
POST /a/{team_slug}/schedule/api/v1/downtime/ Add downtime (closed, maintenance, breakdown) or overtime to a machine or the whole shop.
PATCH /a/{team_slug}/schedule/api/v1/downtime/{id}/ Change a downtime.
DELETE /a/{team_slug}/schedule/api/v1/downtime/{id}/ Remove a downtime.
POST /a/{team_slug}/schedule/api/v1/operations/{id}/events/ Record a floor event on a step: start, pause, resume, done, problem and more.
GET /a/{team_slug}/schedule/api/v1/operations/{id}/explain/ Explain a step: why it starts when it does, other machines, late causes and fixes.
POST /a/{team_slug}/schedule/api/v1/operations/{id}/keep-machine/ Switch Only this machine for a step.
POST /a/{team_slug}/schedule/api/v1/operations/{id}/move/ Put a step on a machine, after or before another step of that machine.
POST /a/{team_slug}/schedule/api/v1/operations/{id}/override/ Set a step's duration by hand, or go back to the estimate.
POST /a/{team_slug}/schedule/api/v1/operations/{id}/pin/ Pin a step: keep it on its machine, not before a time.
POST /a/{team_slug}/schedule/api/v1/operations/{id}/unpin/ Remove a step's pin.
POST /a/{team_slug}/schedule/api/v1/operations/scan/ Scan a job's code: find its step on a machine, and start, finish or resume it.
GET /a/{team_slug}/schedule/api/v1/orders/ List the schedule's jobs.
POST /a/{team_slug}/schedule/api/v1/orders/ Send an imposition job (or all of them) to the schedule, or add a manual job.
GET /a/{team_slug}/schedule/api/v1/orders/{id}/ Read a job with its steps and ready checks.
PATCH /a/{team_slug}/schedule/api/v1/orders/{id}/ Hold or release a job, or change its notes, not-before time, route or (manual jobs) its details.
DELETE /a/{team_slug}/schedule/api/v1/orders/{id}/ Remove a job from the schedule.
PATCH /a/{team_slug}/schedule/api/v1/orders/{id}/checks/{key}/ Tick, untick or waive a job's ready check.
POST /a/{team_slug}/schedule/api/v1/orders/{id}/refresh/ Time a job again from its solution (Review new times).
POST /a/{team_slug}/schedule/api/v1/orders/{id}/steps/ Add a step to a job.
PATCH /a/{team_slug}/schedule/api/v1/orders/{id}/steps/{op_id}/ Rename a step, change its wait or duration, or move it earlier or later in the job's route.
DELETE /a/{team_slug}/schedule/api/v1/orders/{id}/steps/{op_id}/ Skip a step of a job that hasn't started.
POST /a/{team_slug}/schedule/api/v1/orders/{id}/to-tray/ Take a job off the board and back to the tray, to place again.
POST /a/{team_slug}/schedule/api/v1/orders/import/ Add or update jobs from a CSV or a list of rows; a dry run first says what would happen.
GET /a/{team_slug}/schedule/api/v1/orders/import/template/ A CSV template with every column and example rows.
POST /a/{team_slug}/schedule/api/v1/plan/apply/ Apply a previewed plan as one change you can undo.
POST /a/{team_slug}/schedule/api/v1/plan/preview/ Preview Place (new steps only) or Re-plan: nothing changes until you apply it.
GET /a/{team_slug}/schedule/api/v1/plan/preview/{task_id}/ Read a background preview: 202 while it is still working.
GET /a/{team_slug}/schedule/api/v1/resources/ List the schedule's machines.
POST /a/{team_slug}/schedule/api/v1/resources/ Add a machine.
GET /a/{team_slug}/schedule/api/v1/resources/{id}/ Read a machine.
PATCH /a/{team_slug}/schedule/api/v1/resources/{id}/ Change a machine.
DELETE /a/{team_slug}/schedule/api/v1/resources/{id}/ Remove a machine that has no work or history.
POST /a/{team_slug}/schedule/api/v1/resources/{id}/down/ Report a machine down (a breakdown with an expected end).
POST /a/{team_slug}/schedule/api/v1/resources/{id}/up/ Report a machine back up (closes its breakdown).
POST /a/{team_slug}/schedule/api/v1/resources/import-equipment/ Add equipment from the equipment library as machines (all of it, or the listed items).
GET /a/{team_slug}/schedule/api/v1/routes/ List the routes jobs follow.
POST /a/{team_slug}/schedule/api/v1/routes/ Add a route.
GET /a/{team_slug}/schedule/api/v1/routes/{id}/ Read a route.
PATCH /a/{team_slug}/schedule/api/v1/routes/{id}/ Change a route (jobs already on the schedule keep their steps).
DELETE /a/{team_slug}/schedule/api/v1/routes/{id}/ Remove a route (not the fallback route).
GET /a/{team_slug}/schedule/api/v1/routes/{id}/test/ Test a route with an imposition job: its steps, every machine's time, the machines that can't.
GET /a/{team_slug}/schedule/api/v1/settings/ Read the schedule's settings.
PATCH /a/{team_slug}/schedule/api/v1/settings/ Change schedule settings (shop hours, time fence, automation, who can plan…).
GET /a/{team_slug}/schedule/api/v1/stations/{id}/ Read one machine's queue: the step on it, up next, later today and other work it could run.
GET /a/{team_slug}/schedule/api/v1/today/ Read today's floor per machine: its state, the step on it and what is next.

All “scheduling” operations in the API reference

Last updated Oct. 18, 2026