API-Schedule

note

Preliminary: subject to change

The Schedule API exposes Eclipse Pro's per-machine schedule and provides endpoints for driving it externally — placing jobs on hold, assigning jobs to machines, and reordering work. The batch push endpoint runs the same mapping pipeline used by the DB-pull Schedule Sync, so the end state is identical for identical input.

For the data model — what hold and sequencing mean, identifier resolution, and key behaviors that apply to both this API and the DB-pull mechanism — see Schedule (Data Domains).

See API-Getting Connected for the Authorization: ApiKey ... header.

Conventions

• Identifier flexibility (sync only). The push endpoint accepts ordId (canonical), or any unique prefix of the candidate key (orderCode, materialCode, toolingCode). ordId wins if both are present.
• Ambiguous identifiers reject the whole batch. If any row's identifier matches more than one job, the whole batch returns 400 with an ambiguous array; nothing is applied. Not-found (0 matches) is a per-row failure note instead — the rest of the batch still applies.
• Lenient numeric parsing. ordId, machineNumber, and sequence accept JSON numbers (5), numeric strings ("5"), null, and empty string "" (treated as null). Helpful when the source system serializes everything as strings.
• Audit. Every sync call writes a ScheduleSyncEvent document; the response includes the batchId that document is keyed by.

Endpoints

GET /api/v1/schedule/machines (list machine schedules)

A snapshot of every machine and the jobs currently queued on it.

Responses

http code	content-type	response
200	application/json	Array of machine schedules (possibly empty).
401	application/json	Missing or invalid API key.

Response shape

[
  {
    "machineNumber": 1,
    "scheduledFt": 4218.6,
    "atMachineFt": 312.4,
    "scheduleEndDate": "2026-05-23T14:22:00",
    "schedule": [
      {
        "jobId": 100234,
        "orderCode": "WO14-250430",
        "materialCode": "26GA-FG",
        "toolingCode": "T11",
        "isOnMachine": true,
        "startDateTimeUtc": "2026-05-22T17:15:00Z",
        "endDateTimeUtc": "2026-05-22T19:45:00Z",
        "sequenceNum": 1,
        "remainingFt": 312.4
      }
    ]
  }
]

field	description
machineNumber	Machine identifier.
scheduledFt	Total remaining feet across all production blocks on this machine.
atMachineFt	Feet already at the machine (sent and not yet consumed).
scheduleEndDate	Expected completion of the last block. null when the schedule is empty.
schedule[]	Production blocks in scheduled order. sequenceNum is 1-based.

Example cURL

curl -H "Authorization: ApiKey YOUR_KEY" \
     "http://localhost:8080/api/v1/schedule/machines"

POST /api/v1/schedule/setHold (set hold state on one or more jobs)

Set the hold flag on one or more jobs by OrdId. Held jobs that are queued are skipped by the scheduler; held jobs that are at a machine are recalled (and the machine is halted first if currently running). Released jobs (hold=false) return to the queue.

For batch hold + sequencing in one call, or for hold control by orderCode instead of OrdId, use POST /api/v1/schedule/sync.

Parameters

name	location	data type	description
ordId	query	long	The OrdId of the job. Repeat the parameter to set multiple: ?ordId=111&ordId=222.
hold	query	bool	true to place on hold, false to release.

Responses

http code	content-type	response
202	(none)	Accepted — the hold action has been dispatched to the Agent.
400	application/json	{ "errors": [...] } — one or more ordId values failed to parse, or no ordId was supplied.
503	application/json	{ "errors": ["AgentNotAvailable"] } — the Agent is offline.
401	application/json	Missing or invalid API key.

Example cURL

curl -X POST \
     -H "Authorization: ApiKey YOUR_KEY" \
     "http://localhost:8080/api/v1/schedule/setHold?ordId=111&ordId=222&hold=true"

POST /api/v1/schedule/sync (push a batch of schedule rows)

Push a batch of schedule rows. Each row identifies a job and optionally specifies its target hold state, machine, and sequence. The same mapping pipeline used by the DB-pull Schedule Sync applies the result.

See Schedule (Data Domains) for the data model and how the per-row signals interact with each other.

Request shape

{
  "syncMachineSequence": true,
  "holdJobsNotInSyncData": false,
  "records": [
    {
      "ordId": null,
      "orderCode": "WO14-250430",
      "materialCode": null,
      "toolingCode": null,
      "onHold": false,
      "machineNumber": 1,
      "sequence": 1
    },
    {
      "orderCode": "WO14-250431",
      "machineNumber": 1,
      "sequence": 2
    }
  ]
}

Request fields

field	type	description
syncMachineSequence	bool	When true, honor machineNumber/sequence on each row. When false, only onHold is applied.
holdJobsNotInSyncData	bool	When true, hold every existing runnable job whose OrdId is not in this batch.
records[]	array (≥ 1)	Per-job rows. See below.

Record fields

field	type	description
ordId	long?	Canonical job id. If present, the code fields are ignored.
orderCode	string	Required when ordId is null. Exact match against the job's order code.
materialCode	string?	Optional disambiguator. Apply when orderCode alone is not unique.
toolingCode	string?	Optional disambiguator. Apply when orderCode + materialCode is still not unique.
onHold	bool?	Target hold state. null = leave unchanged. See hold control.
machineNumber	int?	Target machine. 0 = explicit unschedule. Only honored when syncMachineSequence is true.
sequence	int?	Target sequence on the machine. null = append. Only honored when syncMachineSequence is true.

ordId, machineNumber, and sequence accept JSON numbers, numeric strings, null, and empty string "" (treated as null).

Responses

http code	content-type	response
200	application/json	Sync result. Per-row failures are listed; the rest of the batch applied.
400	application/json	Validation error. See Error responses below.
503	application/json	{ "errors": ["AgentNotAvailable"] } — the Agent went offline mid-apply. Some rows may have landed before this point.
401	application/json	Missing or invalid API key.

Response shape (200)

{
  "successCount": 1,
  "failures": [
    {
      "recordId": "WO14-250431",
      "messages": ["Unable to identify an OrdId"]
    }
  ],
  "batchId": "ScheduleSyncEvents/42-A"
}

field	description
successCount	records.length minus the number of failures.
failures[]	Per-row failure notes — not-found identifiers, parse errors, "sequence without machineNumber", running-job conflicts, duplicate ordIds on a machine, etc. The rest of the batch was applied.
batchId	Identifier of the persisted ScheduleSyncEvent audit document.

Error responses (400)

Missing identifier — a record has neither ordId nor orderCode:

{
  "errors": [
    "Record at index 2 must specify ordId or orderCode."
  ]
}

Ambiguous identifier — one or more records' identifiers match more than one job. The whole batch is rejected; nothing has been applied:

{
  "errors": ["One or more records matched more than one job."],
  "ambiguous": [
    { "index": 3, "identifier": "WO14-250430", "matchCount": 4 },
    { "index": 9, "identifier": "WO14-250431/26GA-FG", "matchCount": 2 }
  ]
}

Resolve by adding materialCode (and toolingCode if still ambiguous), or by switching to ordId, and resend.

Example cURL

curl -X POST \
     -H "Authorization: ApiKey YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "syncMachineSequence": true,
           "holdJobsNotInSyncData": false,
           "records": [
             { "orderCode": "WO14-250430", "machineNumber": 1, "sequence": 1 },
             { "orderCode": "WO14-250431", "machineNumber": 1, "sequence": 2 }
           ]
         }' \
     "http://localhost:8080/api/v1/schedule/sync"