FactoryFlow API reference

GET/wms/v1/tasks#

List warehouse tasks

listWmsTasks · WMS · task:read

Parameter	In	Required	Schema
X-Correlation-Id	header	Yes	{"type": "string", "minLength": 1, "format": "uuid"}
X-Tenant-Id	header	Yes	{"type": "string", "minLength": 1}
X-Site-Id	header	Yes	{"type": "string", "minLength": 1}
limit	query	No	{"type": "integer", "minimum": 1, "maximum": 100, "default": 20}
cursor	query	No	{"type": "string", "minLength": 1}
status	query	No	{"type": "string", "minLength": 1, "enum": ["CREATED", "VALIDATED", "ALLOCATED", "RELEASED", "ASSIGNED", "IN_PROGRESS", "COMPLETED", "EXCEPTION"]}

TaskPage · schema

Field	Type	Required	Meaning	Constraints
items	array	Yes	Items in the current result page.	{"items": {"$ref": "#/components/schemas/Task"}}
nextCursor	string	No	Cursor for the next page; does not imply all results were reviewed.	{"minLength": 1}

cURL

curl --request GET \
  "https://factoryflow-api.example.invalid/wms/v1/tasks" \
  --header "Authorization: Bearer ${FACTORYFLOW_ACCESS_TOKEN}" \
  --header "X-Tenant-Id: DEMO-TENANT" \
  --header "X-Site-Id: DEMO-SITE" \
  --header "X-Correlation-Id: 00000000-0000-4000-8000-000000000001"

Python

import json, os, urllib.request
base = "https://factoryflow-api.example.invalid"
headers = {'Authorization': 'Bearer ' + os.environ['FACTORYFLOW_ACCESS_TOKEN'], 'X-Tenant-Id': 'DEMO-TENANT', 'X-Site-Id': 'DEMO-SITE', 'X-Correlation-Id': '00000000-0000-4000-8000-000000000001'}
data = None
request = urllib.request.Request(base + "/wms/v1/tasks", data=data, headers=headers, method="GET")
# No request is sent by this offline example.

Java

var builder = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://factoryflow-api.example.invalid/wms/v1/tasks"))
    .header("Authorization", "Bearer " + System.getenv("FACTORYFLOW_ACCESS_TOKEN"))
    .header("X-Tenant-Id", "DEMO-TENANT")
    .header("X-Site-Id", "DEMO-SITE")
    .header("X-Correlation-Id", "00000000-0000-4000-8000-000000000001")
    .GET();
var request = builder.build();
// No send in the offline example.

View sample response · 200

Static data; no request was sent.

{
  "items": [
    {
      "id": "DEMO-TASK",
      "status": "CREATED",
      "version": 1
    }
  ],
  "nextCursor": "DEMO-NEXT"
}

400 · 401 · 403 · 429 · 503 → application/problem+json

Use contracted page limits and cursors; an invalid cursor requires restarting the query, not assuming no tasks remain.

Error conditions and response

For listWmsTasks: 401/403 require identity, scope and site checks; retries cannot bypass authority. Missing resources require identifier and scope checks; absence does not prove mission failure.

POST/wms/v1/tasks#

Create a warehouse task

createWmsTask · WMS · task:create

Parameter	In	Required	Schema
X-Correlation-Id	header	Yes	{"type": "string", "minLength": 1, "format": "uuid"}
X-Tenant-Id	header	Yes	{"type": "string", "minLength": 1}
X-Site-Id	header	Yes	{"type": "string", "minLength": 1}
X-Idempotency-Key	header	Yes	{"type": "string", "minLength": 1}

Sample request body

{
  "taskType": "TRANSFER",
  "siteId": "DEMO-SITE",
  "warehouseId": "DEMO-WH",
  "sourceLocationId": "DEMO-A",
  "targetLocationId": "DEMO-B",
  "lines": [
    {
      "skuId": "DEMO-SKU",
      "quantity": 1,
      "uom": "EA"
    }
  ],
  "executionMode": "AMR"
}

TaskRequest · schema

Field	Type	Required	Meaning	Constraints
taskType	string	Yes	Warehouse work type; determines source/destination requirements.	{"minLength": 1, "enum": ["RECEIVE", "PUTAWAY", "TRANSFER", "REPLENISH", "PICK", "PACK", "CYCLE_COUNT"]}
siteId	string	Yes	Site identifier; must match the authorized context.	{"minLength": 1}
warehouseId	string	Yes	Warehouse belonging to the permitted site.	{"minLength": 1}
sourceLocationId	string	Conditional	Source location; required for TRANSFER or PICK.	{"minLength": 1}
targetLocationId	string	Conditional	Destination; required for PUTAWAY, TRANSFER or REPLENISH.	{"minLength": 1}
lines	array	Yes	Item, quantity and unit lines to process.	{"minItems": 1, "items": {"type": "object", "properties": {"skuId": {"type": "string", "minLength": 1, "description": "Item identifier in selected master data."}, "quantity": {"type": "number", "minimum": 0, "exclusiveMinimum": true, "description": "Positive amount in the line uom; no inferred unit."}, "uom": {"type": "string", "minLength": 1, "description": "Unit code mapped in master data."}}, "required": ["skuId", "quantity", "uom"], "additionalProperties": false}}
executionMode	string	Yes	Intended mode; available only with a supported project profile.	{"minLength": 1, "enum": ["MANUAL", "AMR", "COBOT", "CONVEYOR", "HYBRID"]}

Task · schema

Field	Type	Required	Meaning	Constraints
id	string	Yes	Identifier assigned by the owning service.	{"minLength": 1}
status	string	Yes	State in this object lifecycle; not a substitute for another domain state.	{"minLength": 1, "enum": ["CREATED", "VALIDATED", "ALLOCATED", "RELEASED", "ASSIGNED", "IN_PROGRESS", "COMPLETED", "EXCEPTION"]}
version	integer	Yes	Object revision used to detect concurrent updates.	{"minimum": 1}
siteId	string	No	Site identifier; must match the authorized context.	{}
warehouseId	string	No	Warehouse belonging to the permitted site.	{}
sourceLocationId	string	No	Source location; required for TRANSFER or PICK.	{}
targetLocationId	string	No	Destination; required for PUTAWAY, TRANSFER or REPLENISH.	{}

cURL

curl --request POST \
  "https://factoryflow-api.example.invalid/wms/v1/tasks" \
  --header "Authorization: Bearer ${FACTORYFLOW_ACCESS_TOKEN}" \
  --header "X-Tenant-Id: DEMO-TENANT" \
  --header "X-Site-Id: DEMO-SITE" \
  --header "X-Correlation-Id: 00000000-0000-4000-8000-000000000001" \
  --header "X-Idempotency-Key: DEMO-KEY" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Python

import json, os, urllib.request
base = "https://factoryflow-api.example.invalid"
headers = {'Authorization': 'Bearer ' + os.environ['FACTORYFLOW_ACCESS_TOKEN'], 'X-Tenant-Id': 'DEMO-TENANT', 'X-Site-Id': 'DEMO-SITE', 'X-Correlation-Id': '00000000-0000-4000-8000-000000000001', 'X-Idempotency-Key': 'DEMO-KEY', 'Content-Type': 'application/json'}
data = json.dumps({'taskType': 'TRANSFER', 'siteId': 'DEMO-SITE', 'warehouseId': 'DEMO-WH', 'sourceLocationId': 'DEMO-A', 'targetLocationId': 'DEMO-B', 'lines': [{'skuId': 'DEMO-SKU', 'quantity': 1, 'uom': 'EA'}], 'executionMode': 'AMR'}).encode("utf-8")
request = urllib.request.Request(base + "/wms/v1/tasks", data=data, headers=headers, method="POST")
# No request is sent by this offline example.

Java

var builder = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://factoryflow-api.example.invalid/wms/v1/tasks"))
    .header("Authorization", "Bearer " + System.getenv("FACTORYFLOW_ACCESS_TOKEN"))
    .header("X-Tenant-Id", "DEMO-TENANT")
    .header("X-Site-Id", "DEMO-SITE")
    .header("X-Correlation-Id", "00000000-0000-4000-8000-000000000001")
    .header("Content-Type", "application/json")
    .header("X-Idempotency-Key", "DEMO-KEY")
    .POST(java.net.http.HttpRequest.BodyPublishers.ofFile(java.nio.file.Path.of("request.json")));
var request = builder.build();
// No send in the offline example.

View sample response · 201

Static data; no request was sent.

{
  "id": "DEMO-TASK",
  "status": "CREATED",
  "version": 1
}

400 · 401 · 403 · 429 · 503 · 409 · 422 → application/problem+json

TRANSFER without source or destination is blocked; correct SKU/UOM mapping before creation.

Error conditions and response

For createWmsTask: 401/403 require identity, scope and site checks; retries cannot bypass authority. Writes retain key/body on retry; different bodies need a new intent after reconciliation.

GET/wms/v1/tasks/{taskId}#

Read a warehouse task

getWmsTask · WMS · task:read

Parameter	In	Required	Schema
X-Correlation-Id	header	Yes	{"type": "string", "minLength": 1, "format": "uuid"}
X-Tenant-Id	header	Yes	{"type": "string", "minLength": 1}
X-Site-Id	header	Yes	{"type": "string", "minLength": 1}
taskId	path	Yes	{"type": "string", "minLength": 1}

Task · schema

Field	Type	Required	Meaning	Constraints
id	string	Yes	Identifier assigned by the owning service.	{"minLength": 1}
status	string	Yes	State in this object lifecycle; not a substitute for another domain state.	{"minLength": 1, "enum": ["CREATED", "VALIDATED", "ALLOCATED", "RELEASED", "ASSIGNED", "IN_PROGRESS", "COMPLETED", "EXCEPTION"]}
version	integer	Yes	Object revision used to detect concurrent updates.	{"minimum": 1}
siteId	string	No	Site identifier; must match the authorized context.	{}
warehouseId	string	No	Warehouse belonging to the permitted site.	{}
sourceLocationId	string	No	Source location; required for TRANSFER or PICK.	{}
targetLocationId	string	No	Destination; required for PUTAWAY, TRANSFER or REPLENISH.	{}

cURL

curl --request GET \
  "https://factoryflow-api.example.invalid/wms/v1/tasks/DEMO-ID" \
  --header "Authorization: Bearer ${FACTORYFLOW_ACCESS_TOKEN}" \
  --header "X-Tenant-Id: DEMO-TENANT" \
  --header "X-Site-Id: DEMO-SITE" \
  --header "X-Correlation-Id: 00000000-0000-4000-8000-000000000001"

Python

import json, os, urllib.request
base = "https://factoryflow-api.example.invalid"
headers = {'Authorization': 'Bearer ' + os.environ['FACTORYFLOW_ACCESS_TOKEN'], 'X-Tenant-Id': 'DEMO-TENANT', 'X-Site-Id': 'DEMO-SITE', 'X-Correlation-Id': '00000000-0000-4000-8000-000000000001'}
data = None
request = urllib.request.Request(base + "/wms/v1/tasks/DEMO-ID", data=data, headers=headers, method="GET")
# No request is sent by this offline example.

Java

var builder = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://factoryflow-api.example.invalid/wms/v1/tasks/DEMO-ID"))
    .header("Authorization", "Bearer " + System.getenv("FACTORYFLOW_ACCESS_TOKEN"))
    .header("X-Tenant-Id", "DEMO-TENANT")
    .header("X-Site-Id", "DEMO-SITE")
    .header("X-Correlation-Id", "00000000-0000-4000-8000-000000000001")
    .GET();
var request = builder.build();
// No send in the offline example.

View sample response · 200

Static data; no request was sent.

{
  "id": "DEMO-TASK",
  "status": "IN_PROGRESS",
  "version": 3
}

400 · 401 · 403 · 429 · 503 · 404 → application/problem+json

Check task site authority; interpret COMPLETED within the WMS domain.

Error conditions and response

For getWmsTask: 401/403 require identity, scope and site checks; retries cannot bypass authority. Missing resources require identifier and scope checks; absence does not prove mission failure.

POST/wms/v1/tasks/{taskId}/confirm#

Confirm the business outcome

confirmWmsTask · WMS · task:execute

Parameter	In	Required	Schema
X-Correlation-Id	header	Yes	{"type": "string", "minLength": 1, "format": "uuid"}
X-Tenant-Id	header	Yes	{"type": "string", "minLength": 1}
X-Site-Id	header	Yes	{"type": "string", "minLength": 1}
X-Idempotency-Key	header	Yes	{"type": "string", "minLength": 1}
taskId	path	Yes	{"type": "string", "minLength": 1}

Sample request body

{
  "confirmationType": "SCAN",
  "expectedVersion": 3,
  "evidenceRef": "DEMO-SCAN"
}

Confirmation · schema

Field	Type	Required	Meaning	Constraints
confirmationType	string	Yes	Type of task-confirmation evidence.	{"minLength": 1, "enum": ["SCAN", "DEVICE_EVENT", "MANUAL_OVERRIDE"]}
expectedVersion	integer	Yes	Revision the caller reviewed; stale revisions require reconciliation.	{"minimum": 1}
evidenceRef	string	Yes	Reference to evidence checked for authority and relevance.	{"minLength": 1}

Task · schema

Field	Type	Required	Meaning	Constraints
id	string	Yes	Identifier assigned by the owning service.	{"minLength": 1}
status	string	Yes	State in this object lifecycle; not a substitute for another domain state.	{"minLength": 1, "enum": ["CREATED", "VALIDATED", "ALLOCATED", "RELEASED", "ASSIGNED", "IN_PROGRESS", "COMPLETED", "EXCEPTION"]}
version	integer	Yes	Object revision used to detect concurrent updates.	{"minimum": 1}
siteId	string	No	Site identifier; must match the authorized context.	{}
warehouseId	string	No	Warehouse belonging to the permitted site.	{}
sourceLocationId	string	No	Source location; required for TRANSFER or PICK.	{}
targetLocationId	string	No	Destination; required for PUTAWAY, TRANSFER or REPLENISH.	{}

cURL

curl --request POST \
  "https://factoryflow-api.example.invalid/wms/v1/tasks/DEMO-ID/confirm" \
  --header "Authorization: Bearer ${FACTORYFLOW_ACCESS_TOKEN}" \
  --header "X-Tenant-Id: DEMO-TENANT" \
  --header "X-Site-Id: DEMO-SITE" \
  --header "X-Correlation-Id: 00000000-0000-4000-8000-000000000001" \
  --header "X-Idempotency-Key: DEMO-KEY" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Python

import json, os, urllib.request
base = "https://factoryflow-api.example.invalid"
headers = {'Authorization': 'Bearer ' + os.environ['FACTORYFLOW_ACCESS_TOKEN'], 'X-Tenant-Id': 'DEMO-TENANT', 'X-Site-Id': 'DEMO-SITE', 'X-Correlation-Id': '00000000-0000-4000-8000-000000000001', 'X-Idempotency-Key': 'DEMO-KEY', 'Content-Type': 'application/json'}
data = json.dumps({'confirmationType': 'SCAN', 'expectedVersion': 3, 'evidenceRef': 'DEMO-SCAN'}).encode("utf-8")
request = urllib.request.Request(base + "/wms/v1/tasks/DEMO-ID/confirm", data=data, headers=headers, method="POST")
# No request is sent by this offline example.

Java

var builder = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://factoryflow-api.example.invalid/wms/v1/tasks/DEMO-ID/confirm"))
    .header("Authorization", "Bearer " + System.getenv("FACTORYFLOW_ACCESS_TOKEN"))
    .header("X-Tenant-Id", "DEMO-TENANT")
    .header("X-Site-Id", "DEMO-SITE")
    .header("X-Correlation-Id", "00000000-0000-4000-8000-000000000001")
    .header("Content-Type", "application/json")
    .header("X-Idempotency-Key", "DEMO-KEY")
    .POST(java.net.http.HttpRequest.BodyPublishers.ofFile(java.nio.file.Path.of("request.json")));
var request = builder.build();
// No send in the offline example.

View sample response · 200

Static data; no request was sent.

{
  "id": "DEMO-TASK",
  "status": "COMPLETED",
  "version": 4
}

400 · 401 · 403 · 429 · 503 · 404 · 409 · 422 → application/problem+json

Missing scans or stale expectedVersion block confirmation; reread the task and verify evidence.

Error conditions and response

For confirmWmsTask: 401/403 require identity, scope and site checks; retries cannot bypass authority. Writes retain key/body on retry; different bodies need a new intent after reconciliation.

POST/wcs/v1/execution-orders#

Create an execution order

createExecutionOrder · WCS · wcs:dispatch

Parameter	In	Required	Schema
X-Correlation-Id	header	Yes	{"type": "string", "minLength": 1, "format": "uuid"}
X-Tenant-Id	header	Yes	{"type": "string", "minLength": 1}
X-Site-Id	header	Yes	{"type": "string", "minLength": 1}
X-Idempotency-Key	header	Yes	{"type": "string", "minLength": 1}

Sample request body

{
  "taskId": "DEMO-TASK",
  "expectedTaskVersion": 2,
  "routeRef": "DEMO-ROUTE"
}

ExecutionRequest · schema

Field	Type	Required	Meaning	Constraints
taskId	string	Yes	Reference to the source warehouse task.	{"minLength": 1}
expectedTaskVersion	integer	Yes	Task revision used when creating execution.	{"minimum": 1}
routeRef	string	Yes	Authorized route/map reference.	{"minLength": 1}

Execution · schema

Field	Type	Required	Meaning	Constraints
id	string	Yes	Identifier assigned by the owning service.	{"minLength": 1}
taskId	string	Yes	Reference to the source warehouse task.	{"minLength": 1}
status	string	Yes	State in this object lifecycle; not a substitute for another domain state.	{"minLength": 1, "enum": ["CREATED", "PLANNED", "DISPATCHING", "DISPATCHED", "EXECUTING", "PAUSED", "COMPLETED", "FAILED", "UNKNOWN"]}
version	integer	Yes	Object revision used to detect concurrent updates.	{"minimum": 1}

cURL

curl --request POST \
  "https://factoryflow-api.example.invalid/wcs/v1/execution-orders" \
  --header "Authorization: Bearer ${FACTORYFLOW_ACCESS_TOKEN}" \
  --header "X-Tenant-Id: DEMO-TENANT" \
  --header "X-Site-Id: DEMO-SITE" \
  --header "X-Correlation-Id: 00000000-0000-4000-8000-000000000001" \
  --header "X-Idempotency-Key: DEMO-KEY" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Python

import json, os, urllib.request
base = "https://factoryflow-api.example.invalid"
headers = {'Authorization': 'Bearer ' + os.environ['FACTORYFLOW_ACCESS_TOKEN'], 'X-Tenant-Id': 'DEMO-TENANT', 'X-Site-Id': 'DEMO-SITE', 'X-Correlation-Id': '00000000-0000-4000-8000-000000000001', 'X-Idempotency-Key': 'DEMO-KEY', 'Content-Type': 'application/json'}
data = json.dumps({'taskId': 'DEMO-TASK', 'expectedTaskVersion': 2, 'routeRef': 'DEMO-ROUTE'}).encode("utf-8")
request = urllib.request.Request(base + "/wcs/v1/execution-orders", data=data, headers=headers, method="POST")
# No request is sent by this offline example.

Java

var builder = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://factoryflow-api.example.invalid/wcs/v1/execution-orders"))
    .header("Authorization", "Bearer " + System.getenv("FACTORYFLOW_ACCESS_TOKEN"))
    .header("X-Tenant-Id", "DEMO-TENANT")
    .header("X-Site-Id", "DEMO-SITE")
    .header("X-Correlation-Id", "00000000-0000-4000-8000-000000000001")
    .header("Content-Type", "application/json")
    .header("X-Idempotency-Key", "DEMO-KEY")
    .POST(java.net.http.HttpRequest.BodyPublishers.ofFile(java.nio.file.Path.of("request.json")));
var request = builder.build();
// No send in the offline example.

View sample response · 201

Static data; no request was sent.

{
  "id": "DEMO-EXE",
  "taskId": "DEMO-TASK",
  "status": "CREATED",
  "version": 1
}

400 · 401 · 403 · 429 · 503 · 409 · 422 → application/problem+json

Unreleased or revision-mismatched tasks hold the request for WMS resolution.

Error conditions and response

For createExecutionOrder: 401/403 require identity, scope and site checks; retries cannot bypass authority. Writes retain key/body on retry; different bodies need a new intent after reconciliation.

POST/wcs/v1/execution-orders/{orderId}/dispatch#

Dispatch execution

dispatchExecutionOrder · WCS · wcs:dispatch

Parameter	In	Required	Schema
X-Correlation-Id	header	Yes	{"type": "string", "minLength": 1, "format": "uuid"}
X-Tenant-Id	header	Yes	{"type": "string", "minLength": 1}
X-Site-Id	header	Yes	{"type": "string", "minLength": 1}
X-Idempotency-Key	header	Yes	{"type": "string", "minLength": 1}
orderId	path	Yes	{"type": "string", "minLength": 1}

Sample request body

{
  "expectedVersion": 2,
  "executorRef": "DEMO-EXECUTOR",
  "policyRef": "DEMO-POLICY"
}

DispatchRequest · schema

Field	Type	Required	Meaning	Constraints
expectedVersion	integer	Yes	Revision the caller reviewed; stale revisions require reconciliation.	{"minimum": 1}
executorRef	string	Yes	Executor meeting the order profile.	{"minLength": 1}
policyRef	string	Yes	Policy governing the dispatch decision.	{"minLength": 1}

Execution · schema

Field	Type	Required	Meaning	Constraints
id	string	Yes	Identifier assigned by the owning service.	{"minLength": 1}
taskId	string	Yes	Reference to the source warehouse task.	{"minLength": 1}
status	string	Yes	State in this object lifecycle; not a substitute for another domain state.	{"minLength": 1, "enum": ["CREATED", "PLANNED", "DISPATCHING", "DISPATCHED", "EXECUTING", "PAUSED", "COMPLETED", "FAILED", "UNKNOWN"]}
version	integer	Yes	Object revision used to detect concurrent updates.	{"minimum": 1}

cURL

curl --request POST \
  "https://factoryflow-api.example.invalid/wcs/v1/execution-orders/DEMO-ID/dispatch" \
  --header "Authorization: Bearer ${FACTORYFLOW_ACCESS_TOKEN}" \
  --header "X-Tenant-Id: DEMO-TENANT" \
  --header "X-Site-Id: DEMO-SITE" \
  --header "X-Correlation-Id: 00000000-0000-4000-8000-000000000001" \
  --header "X-Idempotency-Key: DEMO-KEY" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Python

import json, os, urllib.request
base = "https://factoryflow-api.example.invalid"
headers = {'Authorization': 'Bearer ' + os.environ['FACTORYFLOW_ACCESS_TOKEN'], 'X-Tenant-Id': 'DEMO-TENANT', 'X-Site-Id': 'DEMO-SITE', 'X-Correlation-Id': '00000000-0000-4000-8000-000000000001', 'X-Idempotency-Key': 'DEMO-KEY', 'Content-Type': 'application/json'}
data = json.dumps({'expectedVersion': 2, 'executorRef': 'DEMO-EXECUTOR', 'policyRef': 'DEMO-POLICY'}).encode("utf-8")
request = urllib.request.Request(base + "/wcs/v1/execution-orders/DEMO-ID/dispatch", data=data, headers=headers, method="POST")
# No request is sent by this offline example.

Java

var builder = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://factoryflow-api.example.invalid/wcs/v1/execution-orders/DEMO-ID/dispatch"))
    .header("Authorization", "Bearer " + System.getenv("FACTORYFLOW_ACCESS_TOKEN"))
    .header("X-Tenant-Id", "DEMO-TENANT")
    .header("X-Site-Id", "DEMO-SITE")
    .header("X-Correlation-Id", "00000000-0000-4000-8000-000000000001")
    .header("Content-Type", "application/json")
    .header("X-Idempotency-Key", "DEMO-KEY")
    .POST(java.net.http.HttpRequest.BodyPublishers.ofFile(java.nio.file.Path.of("request.json")));
var request = builder.build();
// No send in the offline example.

View sample response · 202

Static data; no request was sent.

{
  "id": "DEMO-EXE",
  "taskId": "DEMO-TASK",
  "status": "DISPATCHING",
  "version": 3
}

400 · 401 · 403 · 429 · 503 · 404 · 409 · 422 → application/problem+json

Wrong route, unavailable executor or failed safety holds dispatch; 202 is not completion.

Error conditions and response

For dispatchExecutionOrder: 401/403 require identity, scope and site checks; retries cannot bypass authority. Writes retain key/body on retry; different bodies need a new intent after reconciliation.

GET/wcs/v1/execution-orders/{orderId}#

Reconcile execution

getExecutionOrder · WCS · wcs:read

Parameter	In	Required	Schema
X-Correlation-Id	header	Yes	{"type": "string", "minLength": 1, "format": "uuid"}
X-Tenant-Id	header	Yes	{"type": "string", "minLength": 1}
X-Site-Id	header	Yes	{"type": "string", "minLength": 1}
orderId	path	Yes	{"type": "string", "minLength": 1}

Execution · schema

Field	Type	Required	Meaning	Constraints
id	string	Yes	Identifier assigned by the owning service.	{"minLength": 1}
taskId	string	Yes	Reference to the source warehouse task.	{"minLength": 1}
status	string	Yes	State in this object lifecycle; not a substitute for another domain state.	{"minLength": 1, "enum": ["CREATED", "PLANNED", "DISPATCHING", "DISPATCHED", "EXECUTING", "PAUSED", "COMPLETED", "FAILED", "UNKNOWN"]}
version	integer	Yes	Object revision used to detect concurrent updates.	{"minimum": 1}

cURL

curl --request GET \
  "https://factoryflow-api.example.invalid/wcs/v1/execution-orders/DEMO-ID" \
  --header "Authorization: Bearer ${FACTORYFLOW_ACCESS_TOKEN}" \
  --header "X-Tenant-Id: DEMO-TENANT" \
  --header "X-Site-Id: DEMO-SITE" \
  --header "X-Correlation-Id: 00000000-0000-4000-8000-000000000001"

Python

import json, os, urllib.request
base = "https://factoryflow-api.example.invalid"
headers = {'Authorization': 'Bearer ' + os.environ['FACTORYFLOW_ACCESS_TOKEN'], 'X-Tenant-Id': 'DEMO-TENANT', 'X-Site-Id': 'DEMO-SITE', 'X-Correlation-Id': '00000000-0000-4000-8000-000000000001'}
data = None
request = urllib.request.Request(base + "/wcs/v1/execution-orders/DEMO-ID", data=data, headers=headers, method="GET")
# No request is sent by this offline example.

Java

var builder = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://factoryflow-api.example.invalid/wcs/v1/execution-orders/DEMO-ID"))
    .header("Authorization", "Bearer " + System.getenv("FACTORYFLOW_ACCESS_TOKEN"))
    .header("X-Tenant-Id", "DEMO-TENANT")
    .header("X-Site-Id", "DEMO-SITE")
    .header("X-Correlation-Id", "00000000-0000-4000-8000-000000000001")
    .GET();
var request = builder.build();
// No send in the offline example.

View sample response · 200

Static data; no request was sent.

{
  "id": "DEMO-EXE",
  "taskId": "DEMO-TASK",
  "status": "EXECUTING",
  "version": 4
}

400 · 401 · 403 · 429 · 503 · 404 → application/problem+json

For UNKNOWN, inspect mission/controller and callbacks rather than infer FAILED.

Error conditions and response

For getExecutionOrder: 401/403 require identity, scope and site checks; retries cannot bypass authority. Missing resources require identifier and scope checks; absence does not prove mission failure.

POST/fleet/v1/missions#

Create a mobile mission

createMission · Fleet · fleet:manage

Parameter	In	Required	Schema
X-Correlation-Id	header	Yes	{"type": "string", "minLength": 1, "format": "uuid"}
X-Tenant-Id	header	Yes	{"type": "string", "minLength": 1}
X-Site-Id	header	Yes	{"type": "string", "minLength": 1}
X-Idempotency-Key	header	Yes	{"type": "string", "minLength": 1}

Sample request body

{
  "executionId": "DEMO-EXE",
  "pickupPoint": "DEMO-A",
  "dropoffPoint": "DEMO-B",
  "fleetProfile": "DEMO-FLEET"
}

MissionRequest · schema

Field	Type	Required	Meaning	Constraints
executionId	string	Yes	Execution order linked to the mission/cell job.	{"minLength": 1}
pickupPoint	string	Yes	Pickup point in the fleet map/profile.	{"minLength": 1}
dropoffPoint	string	Yes	Drop-off point in the fleet map/profile.	{"minLength": 1}
fleetProfile	string	Yes	Fleet profile configured for the site.	{"minLength": 1}

Mission · schema

Field	Type	Required	Meaning	Constraints
id	string	Yes	Identifier assigned by the owning service.	{"minLength": 1}
status	string	Yes	State in this object lifecycle; not a substitute for another domain state.	{"minLength": 1, "enum": ["CREATED", "ACCEPTED", "GOING_TO_PICKUP", "ARRIVED_PICKUP", "LOADED", "GOING_TO_DROPOFF", "ARRIVED_DROPOFF", "UNLOADED", "COMPLETED", "FAILED", "UNKNOWN"]}

cURL

curl --request POST \
  "https://factoryflow-api.example.invalid/fleet/v1/missions" \
  --header "Authorization: Bearer ${FACTORYFLOW_ACCESS_TOKEN}" \
  --header "X-Tenant-Id: DEMO-TENANT" \
  --header "X-Site-Id: DEMO-SITE" \
  --header "X-Correlation-Id: 00000000-0000-4000-8000-000000000001" \
  --header "X-Idempotency-Key: DEMO-KEY" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Python

import json, os, urllib.request
base = "https://factoryflow-api.example.invalid"
headers = {'Authorization': 'Bearer ' + os.environ['FACTORYFLOW_ACCESS_TOKEN'], 'X-Tenant-Id': 'DEMO-TENANT', 'X-Site-Id': 'DEMO-SITE', 'X-Correlation-Id': '00000000-0000-4000-8000-000000000001', 'X-Idempotency-Key': 'DEMO-KEY', 'Content-Type': 'application/json'}
data = json.dumps({'executionId': 'DEMO-EXE', 'pickupPoint': 'DEMO-A', 'dropoffPoint': 'DEMO-B', 'fleetProfile': 'DEMO-FLEET'}).encode("utf-8")
request = urllib.request.Request(base + "/fleet/v1/missions", data=data, headers=headers, method="POST")
# No request is sent by this offline example.

Java

var builder = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://factoryflow-api.example.invalid/fleet/v1/missions"))
    .header("Authorization", "Bearer " + System.getenv("FACTORYFLOW_ACCESS_TOKEN"))
    .header("X-Tenant-Id", "DEMO-TENANT")
    .header("X-Site-Id", "DEMO-SITE")
    .header("X-Correlation-Id", "00000000-0000-4000-8000-000000000001")
    .header("Content-Type", "application/json")
    .header("X-Idempotency-Key", "DEMO-KEY")
    .POST(java.net.http.HttpRequest.BodyPublishers.ofFile(java.nio.file.Path.of("request.json")));
var request = builder.build();
// No send in the offline example.

View sample response · 201

Static data; no request was sent.

{
  "id": "DEMO-MISSION",
  "status": "CREATED"
}

400 · 401 · 403 · 429 · 503 · 409 · 422 → application/problem+json

If execution already has a mission, reconcile the existing ID rather than recreate after a lost response.

Error conditions and response

For createMission: 401/403 require identity, scope and site checks; retries cannot bypass authority. Writes retain key/body on retry; different bodies need a new intent after reconciliation.

GET/fleet/v1/missions/{missionId}#

Read a mission

getMission · Fleet · fleet:read

Parameter	In	Required	Schema
X-Correlation-Id	header	Yes	{"type": "string", "minLength": 1, "format": "uuid"}
X-Tenant-Id	header	Yes	{"type": "string", "minLength": 1}
X-Site-Id	header	Yes	{"type": "string", "minLength": 1}
missionId	path	Yes	{"type": "string", "minLength": 1}

Mission · schema

Field	Type	Required	Meaning	Constraints
id	string	Yes	Identifier assigned by the owning service.	{"minLength": 1}
status	string	Yes	State in this object lifecycle; not a substitute for another domain state.	{"minLength": 1, "enum": ["CREATED", "ACCEPTED", "GOING_TO_PICKUP", "ARRIVED_PICKUP", "LOADED", "GOING_TO_DROPOFF", "ARRIVED_DROPOFF", "UNLOADED", "COMPLETED", "FAILED", "UNKNOWN"]}

cURL

curl --request GET \
  "https://factoryflow-api.example.invalid/fleet/v1/missions/DEMO-ID" \
  --header "Authorization: Bearer ${FACTORYFLOW_ACCESS_TOKEN}" \
  --header "X-Tenant-Id: DEMO-TENANT" \
  --header "X-Site-Id: DEMO-SITE" \
  --header "X-Correlation-Id: 00000000-0000-4000-8000-000000000001"

Python

import json, os, urllib.request
base = "https://factoryflow-api.example.invalid"
headers = {'Authorization': 'Bearer ' + os.environ['FACTORYFLOW_ACCESS_TOKEN'], 'X-Tenant-Id': 'DEMO-TENANT', 'X-Site-Id': 'DEMO-SITE', 'X-Correlation-Id': '00000000-0000-4000-8000-000000000001'}
data = None
request = urllib.request.Request(base + "/fleet/v1/missions/DEMO-ID", data=data, headers=headers, method="GET")
# No request is sent by this offline example.

Java

var builder = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://factoryflow-api.example.invalid/fleet/v1/missions/DEMO-ID"))
    .header("Authorization", "Bearer " + System.getenv("FACTORYFLOW_ACCESS_TOKEN"))
    .header("X-Tenant-Id", "DEMO-TENANT")
    .header("X-Site-Id", "DEMO-SITE")
    .header("X-Correlation-Id", "00000000-0000-4000-8000-000000000001")
    .GET();
var request = builder.build();
// No send in the offline example.

View sample response · 200

Static data; no request was sent.

{
  "id": "DEMO-MISSION",
  "status": "CREATED"
}

400 · 401 · 403 · 429 · 503 · 404 → application/problem+json

Missing IDs may indicate profile or mapping issues; inspect the source fleet before another mission.

Error conditions and response

For getMission: 401/403 require identity, scope and site checks; retries cannot bypass authority. Missing resources require identifier and scope checks; absence does not prove mission failure.

POST/robot-cell/v1/cell-jobs#

Create a cell job

createCellJob · Cell · robot-cell:operate

Parameter	In	Required	Schema
X-Correlation-Id	header	Yes	{"type": "string", "minLength": 1, "format": "uuid"}
X-Tenant-Id	header	Yes	{"type": "string", "minLength": 1}
X-Site-Id	header	Yes	{"type": "string", "minLength": 1}
X-Idempotency-Key	header	Yes	{"type": "string", "minLength": 1}

Sample request body

{
  "executionId": "DEMO-EXE",
  "cellId": "DEMO-CELL",
  "recipeId": "DEMO-RECIPE",
  "recipeVersion": "1"
}

CellRequest · schema

Field	Type	Required	Meaning	Constraints
executionId	string	Yes	Execution order linked to the mission/cell job.	{"minLength": 1}
cellId	string	Yes	Robot cell in the authorized scope.	{"minLength": 1}
recipeId	string	Yes	Recipe identifier within the permitted cell scope.	{"minLength": 1}
recipeVersion	string	Yes	Approved recipe revision for the job.	{"minLength": 1}

CellJob · schema

Field	Type	Required	Meaning	Constraints
id	string	Yes	Identifier assigned by the owning service.	{"minLength": 1}
status	string	Yes	State in this object lifecycle; not a substitute for another domain state.	{"minLength": 1, "enum": ["CREATED", "ACCEPTED", "RUNNING", "COMPLETED", "BLOCKED", "FAILED", "UNKNOWN"]}
recipeVersion	string	Yes	Approved recipe revision for the job.	{"minLength": 1}

cURL

curl --request POST \
  "https://factoryflow-api.example.invalid/robot-cell/v1/cell-jobs" \
  --header "Authorization: Bearer ${FACTORYFLOW_ACCESS_TOKEN}" \
  --header "X-Tenant-Id: DEMO-TENANT" \
  --header "X-Site-Id: DEMO-SITE" \
  --header "X-Correlation-Id: 00000000-0000-4000-8000-000000000001" \
  --header "X-Idempotency-Key: DEMO-KEY" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Python

import json, os, urllib.request
base = "https://factoryflow-api.example.invalid"
headers = {'Authorization': 'Bearer ' + os.environ['FACTORYFLOW_ACCESS_TOKEN'], 'X-Tenant-Id': 'DEMO-TENANT', 'X-Site-Id': 'DEMO-SITE', 'X-Correlation-Id': '00000000-0000-4000-8000-000000000001', 'X-Idempotency-Key': 'DEMO-KEY', 'Content-Type': 'application/json'}
data = json.dumps({'executionId': 'DEMO-EXE', 'cellId': 'DEMO-CELL', 'recipeId': 'DEMO-RECIPE', 'recipeVersion': '1'}).encode("utf-8")
request = urllib.request.Request(base + "/robot-cell/v1/cell-jobs", data=data, headers=headers, method="POST")
# No request is sent by this offline example.

Java

var builder = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://factoryflow-api.example.invalid/robot-cell/v1/cell-jobs"))
    .header("Authorization", "Bearer " + System.getenv("FACTORYFLOW_ACCESS_TOKEN"))
    .header("X-Tenant-Id", "DEMO-TENANT")
    .header("X-Site-Id", "DEMO-SITE")
    .header("X-Correlation-Id", "00000000-0000-4000-8000-000000000001")
    .header("Content-Type", "application/json")
    .header("X-Idempotency-Key", "DEMO-KEY")
    .POST(java.net.http.HttpRequest.BodyPublishers.ofFile(java.nio.file.Path.of("request.json")));
var request = builder.build();
// No send in the offline example.

View sample response · 201

Static data; no request was sent.

{
  "id": "DEMO-JOB",
  "status": "CREATED",
  "recipeVersion": "1"
}

400 · 401 · 403 · 429 · 503 · 409 · 422 → application/problem+json

Recipe/program mismatch or unready cell blocks the job; the cell engineer checks revision and mode.

Error conditions and response

For createCellJob: 401/403 require identity, scope and site checks; retries cannot bypass authority. Writes retain key/body on retry; different bodies need a new intent after reconciliation.

POST/devices/v1/devices/{deviceId}/commands#

Submit a device command intent

createDeviceCommand · Device · device:command

Parameter	In	Required	Schema
X-Correlation-Id	header	Yes	{"type": "string", "minLength": 1, "format": "uuid"}
X-Tenant-Id	header	Yes	{"type": "string", "minLength": 1}
X-Site-Id	header	Yes	{"type": "string", "minLength": 1}
X-Idempotency-Key	header	Yes	{"type": "string", "minLength": 1}
deviceId	path	Yes	{"type": "string", "minLength": 1}

Sample request body

{
  "commandType": "START_JOB",
  "expectedVersion": 1,
  "policyRef": "DEMO-POLICY"
}

CommandRequest · schema

Field	Type	Required	Meaning	Constraints
commandType	string	Yes	Allowlisted command intent, not raw motion.	{"minLength": 1, "enum": ["CREATE_MISSION", "PRINT_LABEL", "READ_WEIGHT", "START_JOB", "PLC_WRITE_SIGNAL"]}
expectedVersion	integer	Yes	Revision the caller reviewed; stale revisions require reconciliation.	{"minimum": 1}
policyRef	string	Yes	Policy governing the dispatch decision.	{"minLength": 1}

Command · schema

Field	Type	Required	Meaning	Constraints
id	string	Yes	Identifier assigned by the owning service.	{"minLength": 1}
status	string	Yes	State in this object lifecycle; not a substitute for another domain state.	{"minLength": 1, "enum": ["CREATED", "SENT", "ACKED", "COMPLETED", "TIMEOUT", "FAILED", "UNKNOWN"]}

cURL

curl --request POST \
  "https://factoryflow-api.example.invalid/devices/v1/devices/DEMO-ID/commands" \
  --header "Authorization: Bearer ${FACTORYFLOW_ACCESS_TOKEN}" \
  --header "X-Tenant-Id: DEMO-TENANT" \
  --header "X-Site-Id: DEMO-SITE" \
  --header "X-Correlation-Id: 00000000-0000-4000-8000-000000000001" \
  --header "X-Idempotency-Key: DEMO-KEY" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Python

import json, os, urllib.request
base = "https://factoryflow-api.example.invalid"
headers = {'Authorization': 'Bearer ' + os.environ['FACTORYFLOW_ACCESS_TOKEN'], 'X-Tenant-Id': 'DEMO-TENANT', 'X-Site-Id': 'DEMO-SITE', 'X-Correlation-Id': '00000000-0000-4000-8000-000000000001', 'X-Idempotency-Key': 'DEMO-KEY', 'Content-Type': 'application/json'}
data = json.dumps({'commandType': 'START_JOB', 'expectedVersion': 1, 'policyRef': 'DEMO-POLICY'}).encode("utf-8")
request = urllib.request.Request(base + "/devices/v1/devices/DEMO-ID/commands", data=data, headers=headers, method="POST")
# No request is sent by this offline example.

Java

var builder = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://factoryflow-api.example.invalid/devices/v1/devices/DEMO-ID/commands"))
    .header("Authorization", "Bearer " + System.getenv("FACTORYFLOW_ACCESS_TOKEN"))
    .header("X-Tenant-Id", "DEMO-TENANT")
    .header("X-Site-Id", "DEMO-SITE")
    .header("X-Correlation-Id", "00000000-0000-4000-8000-000000000001")
    .header("Content-Type", "application/json")
    .header("X-Idempotency-Key", "DEMO-KEY")
    .POST(java.net.http.HttpRequest.BodyPublishers.ofFile(java.nio.file.Path.of("request.json")));
var request = builder.build();
// No send in the offline example.

View sample response · 202

Static data; no request was sent.

{
  "id": "DEMO-COMMAND",
  "status": "CREATED"
}

400 · 401 · 403 · 429 · 503 · 404 · 409 · 422 → application/problem+json

Reject non-allowlisted commands or failed interlocks; no substitute raw command.

Error conditions and response

For createDeviceCommand: 401/403 require identity, scope and site checks; retries cannot bypass authority. Writes retain key/body on retry; different bodies need a new intent after reconciliation.

POST/device-callback/v1/fleet-events#

Receive a fleet callback

receiveFleetEvent · Callback · fleet:event

Parameter	In	Required	Schema
X-Correlation-Id	header	Yes	{"type": "string", "minLength": 1, "format": "uuid"}
X-Tenant-Id	header	Yes	{"type": "string", "minLength": 1}
X-Site-Id	header	Yes	{"type": "string", "minLength": 1}
X-Idempotency-Key	header	Yes	{"type": "string", "minLength": 1}
X-Request-Timestamp	header	No	{"type": "string", "minLength": 1}
X-Request-Signature	header	No	{"type": "string", "minLength": 1}

Sample request body

{
  "eventId": "DEMO-EVENT",
  "correlationId": "00000000-0000-4000-8000-000000000001",
  "entityId": "DEMO-MISSION",
  "entityVersion": 9,
  "eventType": "mission.status.changed",
  "occurredAt": "2026-10-26T00:00:00Z",
  "schemaVersion": "1.0",
  "source": "DEMO-FLEET-ADAPTER",
  "payload": {
    "status": "COMPLETED",
    "executionId": "DEMO-EXE"
  }
}

Callback · schema

Field	Type	Required	Meaning	Constraints
eventId	string	Yes	Event identifier used for deduplication.	{"minLength": 1}
correlationId	string	Yes	Trace identifier across related steps.	{"minLength": 1, "format": "uuid"}
entityId	string	Yes	Entity described by the event.	{"minLength": 1}
entityVersion	integer	Yes	Source entity revision used for ordering checks.	{"minimum": 1}
eventType	string	Yes	Canonical event name in the reference catalogue.	{"minLength": 1}
occurredAt	string	Yes	Source occurrence time in RFC 3339 with time zone.	{"minLength": 1, "format": "date-time"}
schemaVersion	string	Yes	Envelope/schema revision understood by the consumer.	{"minLength": 1, "enum": ["1.0"]}
source	string	Yes	Producing service or adapter.	{"minLength": 1}
payload	#/components/schemas/EventPayload	Yes	Event data; callback receipt does not confirm stock.	{"$ref": "#/components/schemas/EventPayload"}

Receipt · schema

Field	Type	Required	Meaning	Constraints
id	string	Yes	Identifier assigned by the owning service.	{"minLength": 1}
status	string	Yes	State in this object lifecycle; not a substitute for another domain state.	{"minLength": 1, "enum": ["RECEIVED", "DUPLICATE", "QUARANTINED"]}

cURL

curl --request POST \
  "https://factoryflow-api.example.invalid/device-callback/v1/fleet-events" \
  --header "Authorization: Bearer ${FACTORYFLOW_ACCESS_TOKEN}" \
  --header "X-Tenant-Id: DEMO-TENANT" \
  --header "X-Site-Id: DEMO-SITE" \
  --header "X-Correlation-Id: 00000000-0000-4000-8000-000000000001" \
  --header "X-Idempotency-Key: DEMO-KEY" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Python

import json, os, urllib.request
base = "https://factoryflow-api.example.invalid"
headers = {'Authorization': 'Bearer ' + os.environ['FACTORYFLOW_ACCESS_TOKEN'], 'X-Tenant-Id': 'DEMO-TENANT', 'X-Site-Id': 'DEMO-SITE', 'X-Correlation-Id': '00000000-0000-4000-8000-000000000001', 'X-Idempotency-Key': 'DEMO-KEY', 'Content-Type': 'application/json'}
data = json.dumps({'eventId': 'DEMO-EVENT', 'correlationId': '00000000-0000-4000-8000-000000000001', 'entityId': 'DEMO-MISSION', 'entityVersion': 9, 'eventType': 'mission.status.changed', 'occurredAt': '2026-10-26T00:00:00Z', 'schemaVersion': '1.0', 'source': 'DEMO-FLEET-ADAPTER', 'payload': {'status': 'COMPLETED', 'executionId': 'DEMO-EXE'}}).encode("utf-8")
request = urllib.request.Request(base + "/device-callback/v1/fleet-events", data=data, headers=headers, method="POST")
# No request is sent by this offline example.

Java

var builder = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://factoryflow-api.example.invalid/device-callback/v1/fleet-events"))
    .header("Authorization", "Bearer " + System.getenv("FACTORYFLOW_ACCESS_TOKEN"))
    .header("X-Tenant-Id", "DEMO-TENANT")
    .header("X-Site-Id", "DEMO-SITE")
    .header("X-Correlation-Id", "00000000-0000-4000-8000-000000000001")
    .header("Content-Type", "application/json")
    .header("X-Idempotency-Key", "DEMO-KEY")
    .POST(java.net.http.HttpRequest.BodyPublishers.ofFile(java.nio.file.Path.of("request.json")));
var request = builder.build();
// No send in the offline example.

View sample response · 202

Static data; no request was sent.

{
  "id": "DEMO-RECEIPT",
  "status": "RECEIVED"
}

400 · 401 · 403 · 429 · 503 · 409 · 422 → application/problem+json

Deduplicate eventId; reconcile stale entityVersion under contract without regressing state.

Error conditions and response

For receiveFleetEvent: 401/403 require identity, scope and site checks; retries cannot bypass authority. Writes retain key/body on retry; different bodies need a new intent after reconciliation.

POST/exceptions/v1/exceptions#

Raise an operational exception

raiseException · Exception · exception:create

Parameter	In	Required	Schema
X-Correlation-Id	header	Yes	{"type": "string", "minLength": 1, "format": "uuid"}
X-Tenant-Id	header	Yes	{"type": "string", "minLength": 1}
X-Site-Id	header	Yes	{"type": "string", "minLength": 1}
X-Idempotency-Key	header	Yes	{"type": "string", "minLength": 1}

Sample request body

{
  "entityId": "DEMO-MISSION",
  "reasonCode": "DEMO_TIMEOUT",
  "evidenceRef": "DEMO-TRACE",
  "ownerRef": "DEMO-OWNER"
}

ExceptionRequest · schema

Field	Type	Required	Meaning	Constraints
entityId	string	Yes	Entity described by the event.	{"minLength": 1}
reasonCode	string	Yes	Exception reason code for triage and handling.	{"minLength": 1}
evidenceRef	string	Yes	Reference to evidence checked for authority and relevance.	{"minLength": 1}
ownerRef	string	Yes	Reference to the accountable resolver or team.	{"minLength": 1}

Exception · schema

Field	Type	Required	Meaning	Constraints
id	string	Yes	Identifier assigned by the owning service.	{"minLength": 1}
status	string	Yes	State in this object lifecycle; not a substitute for another domain state.	{"minLength": 1, "enum": ["CREATED", "ASSIGNED", "IN_PROGRESS", "RESOLVED", "CLOSED"]}

cURL

curl --request POST \
  "https://factoryflow-api.example.invalid/exceptions/v1/exceptions" \
  --header "Authorization: Bearer ${FACTORYFLOW_ACCESS_TOKEN}" \
  --header "X-Tenant-Id: DEMO-TENANT" \
  --header "X-Site-Id: DEMO-SITE" \
  --header "X-Correlation-Id: 00000000-0000-4000-8000-000000000001" \
  --header "X-Idempotency-Key: DEMO-KEY" \
  --header "Content-Type: application/json" \
  --data-binary @request.json

Python

import json, os, urllib.request
base = "https://factoryflow-api.example.invalid"
headers = {'Authorization': 'Bearer ' + os.environ['FACTORYFLOW_ACCESS_TOKEN'], 'X-Tenant-Id': 'DEMO-TENANT', 'X-Site-Id': 'DEMO-SITE', 'X-Correlation-Id': '00000000-0000-4000-8000-000000000001', 'X-Idempotency-Key': 'DEMO-KEY', 'Content-Type': 'application/json'}
data = json.dumps({'entityId': 'DEMO-MISSION', 'reasonCode': 'DEMO_TIMEOUT', 'evidenceRef': 'DEMO-TRACE', 'ownerRef': 'DEMO-OWNER'}).encode("utf-8")
request = urllib.request.Request(base + "/exceptions/v1/exceptions", data=data, headers=headers, method="POST")
# No request is sent by this offline example.

Java

var builder = java.net.http.HttpRequest.newBuilder(java.net.URI.create("https://factoryflow-api.example.invalid/exceptions/v1/exceptions"))
    .header("Authorization", "Bearer " + System.getenv("FACTORYFLOW_ACCESS_TOKEN"))
    .header("X-Tenant-Id", "DEMO-TENANT")
    .header("X-Site-Id", "DEMO-SITE")
    .header("X-Correlation-Id", "00000000-0000-4000-8000-000000000001")
    .header("Content-Type", "application/json")
    .header("X-Idempotency-Key", "DEMO-KEY")
    .POST(java.net.http.HttpRequest.BodyPublishers.ofFile(java.nio.file.Path.of("request.json")));
var request = builder.build();
// No send in the offline example.

View sample response · 201

Static data; no request was sent.

{
  "id": "DEMO-EXCEPTION",
  "status": "CREATED"
}

400 · 401 · 403 · 429 · 503 · 409 · 422 → application/problem+json

reasonCode and object require sufficient context; assign a resolver when physical outcomes remain unclear.

Error conditions and response

For raiseException: 401/403 require identity, scope and site checks; retries cannot bypass authority. Writes retain key/body on retry; different bodies need a new intent after reconciliation.

FactoryFlow API reference

List warehouse tasks

Create a warehouse task

Sample request body

Read a warehouse task

Confirm the business outcome

Sample request body

Create an execution order

Sample request body

Dispatch execution

Sample request body

Reconcile execution

Create a mobile mission

Sample request body

Read a mission

Create a cell job

Sample request body

Submit a device command intent

Sample request body

Receive a fleet callback

Sample request body

Raise an operational exception

Sample request body

Version and changes

Search the website

Open an external link

GoPaperless SSO