API-Warehouse Tasks

note

Preliminary: subject to change

The Warehouse Tasks API surfaces Eclipse Pro's material-movement tasks — the same tasks the Warehouse PWA shows — and exposes the state transitions that drive a task from Ready through InProcess → InTransit → Complete. The set is filtered by license: only tasks whose machine carries the pro.machine.warehouse claim are visible.

When a state transition also moves a coil (complete, cancel), Eclipse Pro writes the new location through to Classic (coils.dbf STORELOC) via the Agent before accepting the transition. If the Agent is offline, the request fails with 503 and nothing changes — Classic and Eclipse Pro stay in sync.

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

Conventions

Location values are bare codes like "MACH01" or "WHSE00", not Raven document ids.
State transitions are 202 Accepted, not 200 OK. The Classic write-back (when applicable) is synchronous, but the in-Eclipse-Pro task-state change is queued through an in-process dispatcher. A GET immediately after a POST may not yet reflect the new state.
License gate. Tasks are visible only when their machine carries the pro.machine.warehouse claim. The list endpoint returns only matching tasks; the by-id endpoint returns 403 with { "errors": ["NotLicensedForMachineWarehouse"] } when an id resolves to a task on an unlicensed machine.
Operator identity. Action endpoints that claim the task (inProcess, inTransit, complete, unattainable) accept an optional userName in the body — the operator your system records as having performed the action. Resolution order: body.userName if present → the task's existing userName from a prior call → the API key's principal name. ready and cancel clear userName (release / abort semantics) and do not accept a userName field.

Endpoints

GET /api/v1/warehouseTasks (list tasks)

Parameters

name type data type description
onlyIncomplete optional bool When true, exclude tasks in state Complete. Default false.
taskState optional enum One of Pending, Ready, InProcess, InTransit, Complete.
taskType optional enum WarehouseToMachine or MachineToWarehouse.
destinationLocation optional string Exact match on the destination location code.
requiredAfter optional datetime Inclusive lower bound on requiredDate.
requiredBefore optional datetime Inclusive upper bound on requiredDate.
skip optional int Items to skip. Default 0.
take optional int Items to take. Default 100, max 1000.

name	type	data type	description
`onlyIncomplete`	optional	bool	When `true`, exclude tasks in state `Complete`. Default `false`.
`taskState`	optional	enum	One of `Pending`, `Ready`, `InProcess`, `InTransit`, `Complete`.
`taskType`	optional	enum	`WarehouseToMachine` or `MachineToWarehouse`.
`destinationLocation`	optional	string	Exact match on the destination location code.
`requiredAfter`	optional	datetime	Inclusive lower bound on `requiredDate`.
`requiredBefore`	optional	datetime	Inclusive upper bound on `requiredDate`.
`skip`	optional	int	Items to skip. Default `0`.
`take`	optional	int	Items to take. Default `100`, max `1000`.

Responses

http code content-type response
200 application/json Array of tasks (possibly empty; empty when no machine is warehouse-licensed).
401 application/json Missing or invalid API key.

http code	content-type	response
`200`	`application/json`	Array of tasks (possibly empty; empty when no machine is warehouse-licensed).
`401`	`application/json`	Missing or invalid API key.

Response shape

[
  {
    "taskId": "2354-A",
    "taskType": "WarehouseToMachine",
    "taskState": "Ready",
    "coilType": {
      "coilTypeCode": "122894525",
      "materialType": "STEEL",
      "color": "ASH GREY",
      "gauge": 26,
      "widthIn": 42.75,
      "lbsPerFt": 2.616
    },
    "requiredFt": 1594.4,
    "sourceLocation": "WHSE00",
    "destinationLocation": "MACH01",
    "requiredDate": "2026-05-20T20:58:55Z",
    "availableDate": null,
    "startedDate": null,
    "completedDate": null,
    "selectedCoilId": null,
    "preferredCoilIds": ["1006782922"]
  }
]

field	description
`taskId`	Task identifier (the document-id suffix; not a full Raven id).
`taskType`	`WarehouseToMachine` or `MachineToWarehouse`.
`taskState`	`Pending`, `Ready`, `InProcess`, `InTransit`, or `Complete`.
`coilType`	Required coil-type attributes for fulfillment.
`sourceLocation`	Source location code (bare).
`destinationLocation`	Destination location code (bare).
`selectedCoilId`	The coil chosen to fulfill the task (set on `inTransit`); `null` until then.
`preferredCoilIds`	Coil ids that match the task's coil-type requirements; selecting one of these does not require an override reason.

Example cURL

curl -H "Authorization: ApiKey YOUR_KEY" \
     "http://localhost:8080/api/v1/warehouseTasks?onlyIncomplete=true&destinationLocation=MACH01"

GET /api/v1/warehouseTasks/{taskId} (get one task)

Parameters

name location data type description
taskId path string The task id (without the "MaterialTasks/" prefix).

name	location	data type	description
`taskId`	path	string	The task id (without the `"MaterialTasks/"` prefix).

Responses

http code content-type response
200 application/json Task object.
403 application/json { "errors": ["NotLicensedForMachineWarehouse"] }. The task's machine is not warehouse-licensed.
404 application/json { "errors": ["No warehouse task with id ..."] }.
401 application/json Missing or invalid API key.

http code	content-type	response
`200`	`application/json`	Task object.
`403`	`application/json`	`{ "errors": ["NotLicensedForMachineWarehouse"] }`. The task's machine is not warehouse-licensed.
`404`	`application/json`	`{ "errors": ["No warehouse task with id ..."] }`.
`401`	`application/json`	Missing or invalid API key.

GET /api/v1/warehouseTasks/reasonCodes (reason codes reference)

Reason codes used for override reasons on inTransit and unattainable codes on unattainable.

Responses

http code content-type response
200 application/json Array of reason codes (possibly empty if no machine is warehouse-licensed).
401 application/json Missing or invalid API key.

http code	content-type	response
`200`	`application/json`	Array of reason codes (possibly empty if no machine is warehouse-licensed).
`401`	`application/json`	Missing or invalid API key.

Response shape

[
  { "id": "abc-123", "codeSet": "OverrideReasons",    "reason": "Operator approved non-preferred coil" },
  { "id": "xyz-789", "codeSet": "UnattainableReasons","reason": "Material not in stock" }
]

Use the id value as overrideReason (for inTransit) or unattainableCode (for unattainable).

GET /api/v1/warehouseTasks/locations (locations reference)

The full list of storage locations.

Parameters

name type data type description
category optional enum Filter by category. One of Machine, Warehouse, StagingBay, LoadingDock, Bin.

name	type	data type	description
`category`	optional	enum	Filter by category. One of `Machine`, `Warehouse`, `StagingBay`, `LoadingDock`, `Bin`.

Responses

http code content-type response
200 application/json Array of locations (possibly empty if no machine is warehouse-licensed).
401 application/json Missing or invalid API key.

http code	content-type	response
`200`	`application/json`	Array of locations (possibly empty if no machine is warehouse-licensed).
`401`	`application/json`	Missing or invalid API key.

Response shape

[
  { "code": "WHSE00", "name": "Main Warehouse", "category": "Warehouse" },
  { "code": "MACH01", "name": "Machine 1",     "category": "Machine"   }
]

State transitions

All transitions return 202 Accepted on success — the task-state change is queued through an in-process dispatcher.

Common responses for every transition:

http code	meaning
`202`	Accepted. For `complete` / `cancel` the Classic write-back ran synchronously; for the others, no Classic write-back was needed.
`400`	Validation failure (missing body field, unknown reason code, etc.). Body: `{ "errors": [...] }`.
`403`	Task exists but its machine is not warehouse-licensed. Body: `{ "errors": ["NotLicensedForMachineWarehouse"] }`.
`404`	No task with that id. Body: `{ "errors": ["No warehouse task with id ..."] }`.
`503`	Only `complete` and `cancel`. Classic agent is offline; nothing changed. Body: `{ "errors": ["AgentNotAvailable"] }`.
`401`	Missing or invalid API key.

POST /api/v1/warehouseTasks/{taskId}/ready (release task back to Ready)

Returns the task to Ready state and clears any in-progress fields. Releases the task — userName is cleared.

Body

None. The endpoint takes no body.

Example cURL

curl -X POST \
     -H "Authorization: ApiKey YOUR_KEY" \
     "http://localhost:8080/api/v1/warehouseTasks/2354-A/ready"

POST /api/v1/warehouseTasks/{taskId}/inProcess (operator claims task)

Marks the task as InProcess. Records the operator on the task; subsequent transitions inherit this operator unless they pass a different userName.

Body

{ "userName": "jsmith" }

The body itself is optional; when omitted (or userName omitted) the API-key principal name is used.

Example cURL

curl -X POST \
     -H "Authorization: ApiKey YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{"userName":"jsmith"}' \
     "http://localhost:8080/api/v1/warehouseTasks/2354-A/inProcess"

POST /api/v1/warehouseTasks/{taskId}/inTransit (operator selected a coil)

Marks the task as InTransit against a specific coil. The coil is recorded as selectedCoilId on the task.

If the chosen coil is not in preferredCoilIds, supply an overrideReason from the reason codes (codeSet == OverrideReasons). Whether to require an override is the calling system's decision — the API does not enforce it, but the value is recorded with the task.

Body

{
  "coilId": "1006782922",
  "overrideReason": "Operator approved non-preferred coil",
  "userName": "jsmith"
}

field	required	description
`coilId`	yes	The coil chosen to fulfill the task.
`overrideReason`	no	Free-form override reason text; recorded as an `OverrideReasons` code.
`userName`	no	Operator identity. See Operator identity.

Example cURL

curl -X POST \
     -H "Authorization: ApiKey YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{"coilId":"1006782922","userName":"jsmith"}' \
     "http://localhost:8080/api/v1/warehouseTasks/2354-A/inTransit"

POST /api/v1/warehouseTasks/{taskId}/complete (coil delivered)

Marks the task as Complete and records the location where the coil now resides. The Classic agent is updated synchronously before the task-state transition is queued — a 503 here means nothing changed in either system.

Body

{
  "location": "MACH01",
  "userName": "jsmith"
}

field	required	description
`location`	yes	Destination location code. Must match an existing `LocationV1.code`.
`userName`	no	Operator identity. See Operator identity.

Example cURL

curl -X POST \
     -H "Authorization: ApiKey YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{"location":"MACH01","userName":"jsmith"}' \
     "http://localhost:8080/api/v1/warehouseTasks/2354-A/complete"

POST /api/v1/warehouseTasks/{taskId}/unattainable (task cannot be fulfilled)

Marks the task with an unattainable reason. The task is not transitioned out of its current state by this call.

Body

{
  "unattainableCode": "xyz-789",
  "userName": "jsmith"
}

field	required	description
`unattainableCode`	yes	A reason-code id from reason codes with `codeSet == UnattainableReasons`.
`userName`	no	Operator identity. See Operator identity.

Example cURL

curl -X POST \
     -H "Authorization: ApiKey YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{"unattainableCode":"xyz-789","userName":"jsmith"}' \
     "http://localhost:8080/api/v1/warehouseTasks/2354-A/unattainable"

POST /api/v1/warehouseTasks/{taskId}/cancel (abort task, return coil)

Aborts the task: clears the selected coil and override, returns the task to Ready, and records where the coil currently sits. The Classic agent is updated synchronously before the task-state transition is queued — a 503 here means nothing changed in either system.

Body

{
  "coilId": "1006782922",
  "location": "WHSE00"
}

field	required	description
`coilId`	yes	The coil that was being moved.
`location`	yes	Where the coil currently resides (where it was returned to).

userName is not accepted — cancel clears the operator on the task.

Example cURL

curl -X POST \
     -H "Authorization: ApiKey YOUR_KEY" \
     -H "Content-Type: application/json" \
     -d '{"coilId":"1006782922","location":"WHSE00"}' \
     "http://localhost:8080/api/v1/warehouseTasks/2354-A/cancel"

Conventions​

Endpoints​

Parameters​

Responses​

Response shape​

Example cURL​

Parameters​

Responses​

Responses​

Response shape​

Parameters​

Responses​

Response shape​

State transitions​

Body​

Example cURL​

Body​

Example cURL​

Body​

Example cURL​

Body​

Example cURL​

Body​

Example cURL​

Body​

Example cURL​

Conventions

Endpoints

Parameters

Responses

Response shape

Example cURL

Parameters

Responses

Responses

Response shape

Parameters

Responses

Response shape

State transitions

Body

Example cURL

Body

Example cURL

Body

Example cURL

Body

Example cURL

Body

Example cURL

Body

Example cURL