Schedule API

The Schedule API does what the Schedule pages do: it reads the board, adds imposed jobs, changes the plan, and records what happens on the floor. Use it to feed the Schedule from a machine's own controller, show the queue on another screen, or add jobs from another system. 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#

Due dates, customers and priorities belong to the imposition job: change them with the Imposition API.

Plan changes#

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.

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. Changes need a team administrator, 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#