{ "openapi": "3.1.0", "info": { "title": "EightyOne API", "version": "1", "description": "Public API. Authenticate with a user-owned API key (`Authorization: Bearer `); a key acts as its owner in one company, narrowed to its permissions. Errors are RFC 9457 problem details." }, "servers": [ { "url": "https://api.eightyone.app" } ], "security": [ { "apiKey": [] } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "WorkOS user-owned API key" } }, "schemas": { "Problem": { "type": "object", "required": [ "type", "title", "status", "code" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "instance": { "type": "string" }, "code": { "type": "string", "description": "Stable machine-readable reason" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "paths": { "/api/v1/analytics/downtime": { "get": { "operationId": "analytics.downtime", "summary": "Downtime by machine", "description": "Time each machine (SSU) spent DOWN or in MAINTENANCE in the window, most first, with how many times it entered that state. For the reasons, follow up with downtime_events.list (reason-coded stoppages) or storylines.ssu (the machine's story).\n\nPermission: `insights:view`.", "tags": [ "Analytics" ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Window start (ISO 8601). Default: 30 days before `to`", "schema": { "description": "Window start (ISO 8601). Default: 30 days before `to`", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] } }, { "name": "to", "in": "query", "required": false, "description": "Window end, exclusive (ISO 8601). Default: now", "schema": { "description": "Window end, exclusive (ISO 8601). Default: now", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "from", "to" ], "additionalProperties": false }, "data": { "type": "array", "items": { "type": "object", "properties": { "ssuId": { "description": "SSU external id", "type": [ "string", "null" ] }, "ssuName": { "type": [ "string", "null" ] }, "category": { "type": "string", "description": "DOWN or MAINTENANCE" }, "seconds": { "type": "number" }, "hours": { "type": "number" }, "transitions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Times the machine entered this state" } }, "required": [ "ssuId", "ssuName", "category", "seconds", "hours", "transitions" ], "additionalProperties": false } } }, "required": [ "range", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "analytics.downtime", "x-eightyone-permission": "insights:view", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/analytics/failure-pareto": { "get": { "operationId": "analytics.failure_pareto", "summary": "Failure modes (Pareto)", "description": "What breaks most: completed failure-coded tasks grouped by problem code, most frequent first (top 25), with the machine that suffers each mode most.\n\nPermission: `insights:view`.", "tags": [ "Analytics" ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Window start (ISO 8601). Default: 30 days before `to`", "schema": { "description": "Window start (ISO 8601). Default: 30 days before `to`", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] } }, { "name": "to", "in": "query", "required": false, "description": "Window end, exclusive (ISO 8601). Default: now", "schema": { "description": "Window end, exclusive (ISO 8601). Default: now", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "from", "to" ], "additionalProperties": false }, "data": { "type": "array", "items": { "type": "object", "properties": { "problemCodeId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "worstSsuName": { "type": [ "string", "null" ] } }, "required": [ "problemCodeId", "code", "label", "count", "worstSsuName" ], "additionalProperties": false } } }, "required": [ "range", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "analytics.failure_pareto", "x-eightyone-permission": "insights:view", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/analytics/oee": { "get": { "operationId": "analytics.oee", "summary": "OEE by machine", "description": "Overall equipment effectiveness per machine: availability, performance and quality (0–1) with good / scrap quantities. A factor is null when its source data is missing (no routed work, no counts).\n\nPermission: `insights:view`.", "tags": [ "Analytics" ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Window start (ISO 8601). Default: 30 days before `to`", "schema": { "description": "Window start (ISO 8601). Default: 30 days before `to`", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] } }, { "name": "to", "in": "query", "required": false, "description": "Window end, exclusive (ISO 8601). Default: now", "schema": { "description": "Window end, exclusive (ISO 8601). Default: now", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "from", "to" ], "additionalProperties": false }, "data": { "type": "array", "items": { "type": "object", "properties": { "ssuId": { "description": "SSU external id", "type": [ "string", "null" ] }, "ssuName": { "type": [ "string", "null" ] }, "plannedSeconds": { "type": "number" }, "downtimeSeconds": { "type": "number" }, "availability": { "type": [ "number", "null" ] }, "performance": { "description": "Can exceed 1 when the line beats its standards", "type": [ "number", "null" ] }, "quality": { "type": [ "number", "null" ] }, "goodQuantity": { "type": "number" }, "scrapQuantity": { "type": "number" }, "oee": { "type": [ "number", "null" ] } }, "required": [ "ssuId", "ssuName", "plannedSeconds", "downtimeSeconds", "availability", "performance", "quality", "goodQuantity", "scrapQuantity", "oee" ], "additionalProperties": false } } }, "required": [ "range", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "analytics.oee", "x-eightyone-permission": "insights:view", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/analytics/overview": { "get": { "operationId": "analytics.overview", "summary": "Factory performance overview", "description": "Headline numbers for a window: total downtime, failures, average availability and OEE, and how many machines are monitored. `unavailableMetrics` names OEE factors with no source data yet. Start here, then drill into analytics.downtime / analytics.reliability.\n\nPermission: `insights:view`.", "tags": [ "Analytics" ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Window start (ISO 8601). Default: 30 days before `to`", "schema": { "description": "Window start (ISO 8601). Default: 30 days before `to`", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] } }, { "name": "to", "in": "query", "required": false, "description": "Window end, exclusive (ISO 8601). Default: now", "schema": { "description": "Window end, exclusive (ISO 8601). Default: now", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "from", "to" ], "additionalProperties": false }, "downtimeSeconds": { "type": "number" }, "downtimeHours": { "type": "number" }, "failures": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "avgAvailability": { "description": "0–1", "type": [ "number", "null" ] }, "avgOee": { "description": "0–1", "type": [ "number", "null" ] }, "monitoredSsus": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unavailableMetrics": { "type": "array", "items": { "type": "string" } } }, "required": [ "range", "downtimeSeconds", "downtimeHours", "failures", "avgAvailability", "avgOee", "monitoredSsus", "unavailableMetrics" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "analytics.overview", "x-eightyone-permission": "insights:view", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/analytics/reliability": { "get": { "operationId": "analytics.reliability", "summary": "Machine reliability (MTTR / MTBF)", "description": "Per machine: failures (entries into DOWN), mean time to repair and mean time between failures, in seconds, most failures first.\n\nPermission: `insights:view`.", "tags": [ "Analytics" ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Window start (ISO 8601). Default: 30 days before `to`", "schema": { "description": "Window start (ISO 8601). Default: 30 days before `to`", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] } }, { "name": "to", "in": "query", "required": false, "description": "Window end, exclusive (ISO 8601). Default: now", "schema": { "description": "Window end, exclusive (ISO 8601). Default: now", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "from", "to" ], "additionalProperties": false }, "data": { "type": "array", "items": { "type": "object", "properties": { "ssuId": { "description": "SSU external id", "type": [ "string", "null" ] }, "ssuName": { "type": [ "string", "null" ] }, "failures": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "mttrSeconds": { "type": [ "number", "null" ] }, "mtbfSeconds": { "type": [ "number", "null" ] } }, "required": [ "ssuId", "ssuName", "failures", "mttrSeconds", "mtbfSeconds" ], "additionalProperties": false } } }, "required": [ "range", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "analytics.reliability", "x-eightyone-permission": "insights:view", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/clients": { "get": { "operationId": "clients.list", "summary": "List clients", "description": "The company's clients (the customers whose sites and SSUs work happens at), newest first. Filter by name or active flag.\n\nPermission: `member`.", "tags": [ "Clients" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size (1–100, default 50)", "schema": { "default": 50, "description": "Page size (1–100, default 50)", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Rows to skip", "schema": { "default": 0, "description": "Rows to skip", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "search", "in": "query", "required": false, "description": "Case-insensitive name contains", "schema": { "description": "Case-insensitive name contains", "type": "string" } }, { "name": "isActive", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "description": "Your id for the client (its external system id). null for clients created in EightyOne without one: they are listed, but can't be fetched or changed by id over the API", "type": [ "string", "null" ] }, "name": { "type": "string" }, "isActive": { "type": "boolean" }, "contactPersonName": { "type": [ "string", "null" ] }, "contactPersonEmail": { "type": [ "string", "null" ] }, "contactPersonPhone": { "type": [ "string", "null" ] }, "freeText": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "isDefault": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "isActive", "contactPersonName", "contactPersonEmail", "contactPersonPhone", "freeText", "color", "isDefault", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "offset", "total", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "clients.list", "x-eightyone-permission": "member", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" }, "post": { "operationId": "clients.create", "summary": "Create a client", "description": "Create a client with your own id for it (used to address it afterwards). Fires the client.created webhook.\n\nPermission: `clients:manage`.", "tags": [ "Clients" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "description": "Your id for the client; must be unique in the company" }, "name": { "type": "string", "minLength": 1 }, "contactPersonName": { "type": [ "string", "null" ] }, "contactPersonEmail": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "contactPersonPhone": { "type": [ "string", "null" ] }, "freeText": { "type": [ "string", "null" ] }, "color": { "type": "string" }, "isDefault": { "type": "boolean", "description": "Make this the company's default client (unsets the previous default)" } }, "required": [ "id", "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Your id for the client (its external system id). null for clients created in EightyOne without one: they are listed, but can't be fetched or changed by id over the API", "type": [ "string", "null" ] }, "name": { "type": "string" }, "isActive": { "type": "boolean" }, "contactPersonName": { "type": [ "string", "null" ] }, "contactPersonEmail": { "type": [ "string", "null" ] }, "contactPersonPhone": { "type": [ "string", "null" ] }, "freeText": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "isDefault": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "isActive", "contactPersonName", "contactPersonEmail", "contactPersonPhone", "freeText", "color", "isDefault", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "clients.create", "x-eightyone-permission": "clients:manage", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "transactional" } }, "/api/v1/clients/{id}": { "get": { "operationId": "clients.get", "summary": "Get a client", "description": "One client by your id for it.\n\nPermission: `member`.", "tags": [ "Clients" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Your id for the client (its external system id). null for clients created in EightyOne without one: they are listed, but can't be fetched or changed by id over the API", "type": [ "string", "null" ] }, "name": { "type": "string" }, "isActive": { "type": "boolean" }, "contactPersonName": { "type": [ "string", "null" ] }, "contactPersonEmail": { "type": [ "string", "null" ] }, "contactPersonPhone": { "type": [ "string", "null" ] }, "freeText": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "isDefault": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "isActive", "contactPersonName", "contactPersonEmail", "contactPersonPhone", "freeText", "color", "isDefault", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "clients.get", "x-eightyone-permission": "member", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" }, "patch": { "operationId": "clients.update", "summary": "Update a client", "description": "Change any of a client's fields; only the fields sent change.\n\nPermission: `clients:manage`.", "tags": [ "Clients" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "isActive": { "type": "boolean" }, "contactPersonName": { "type": [ "string", "null" ] }, "contactPersonEmail": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "contactPersonPhone": { "type": [ "string", "null" ] }, "freeText": { "type": [ "string", "null" ] }, "color": { "type": "string" }, "isDefault": { "type": "boolean", "description": "Make this the company's default client (unsets the previous default)" } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Your id for the client (its external system id). null for clients created in EightyOne without one: they are listed, but can't be fetched or changed by id over the API", "type": [ "string", "null" ] }, "name": { "type": "string" }, "isActive": { "type": "boolean" }, "contactPersonName": { "type": [ "string", "null" ] }, "contactPersonEmail": { "type": [ "string", "null" ] }, "contactPersonPhone": { "type": [ "string", "null" ] }, "freeText": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "isDefault": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "isActive", "contactPersonName", "contactPersonEmail", "contactPersonPhone", "freeText", "color", "isDefault", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "clients.update", "x-eightyone-permission": "clients:manage", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "transactional" }, "delete": { "operationId": "clients.delete", "summary": "Delete a client", "description": "Delete (archive) a client. Its history is kept.\n\nPermission: `clients:manage`.", "tags": [ "Clients" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "responses": { "204": { "description": "Success", "content": { "application/json": { "schema": { "type": "null" } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "clients.delete", "x-eightyone-permission": "clients:manage", "x-eightyone-effect": "destructive", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "transactional" } }, "/api/v1/config/apply": { "post": { "operationId": "config.apply", "summary": "Apply a factory spec", "description": "Converges the company's setup to the spec, through the same rules as the dashboard; every change is audited. Safe to re-run: unchanged items are skipped. Not one transaction: if a change fails, the ones before it stay and the result says where it stopped; fix the cause and apply again. Always run config.plan first and get the user's go-ahead.\n\nPermission: `settings:manage or task_types:manage or clients:manage or inventory:manage or products:manage or production:manage or mobile_builder:manage or machine_data:manage or maintenance:manage or flows:manage or quality:manage or permissions:manage or personnel:manage or subcontractors:manage or ai_guidance:manage`.", "tags": [ "Commissioning" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spec": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "settings": { "type": "object", "properties": { "mobileColor": { "type": [ "string", "null" ] }, "polygonRadius": { "description": "Geofence radius in meters", "type": [ "number", "null" ] }, "dueDateReminderDays": { "description": "0 = off", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "subcontractorExpirationReminderDays": { "description": "0 = off", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "createdTaskAsReady": { "type": "boolean" }, "useSubmittedStatus": { "type": "boolean" }, "kittingAlwaysGenerate": { "type": "boolean" }, "defaultTaskView": { "type": [ "string", "null" ] }, "additionalLanguages": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "assigneePriorityOrder": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "productionOutputStorageUnit": { "description": "Where finished production goes: \" / \"", "type": "string" }, "ncrTaskType": { "description": "Task type used for non-conformance reports (NCRs)", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "kittingTaskType": { "description": "Task type used for kitting work orders", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "documentApprovalTaskType": { "description": "Task type used to approve documents", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "ecnTaskType": { "description": "Task type used for engineering change notices", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] } }, "additionalProperties": false }, "ssuStatuses": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "category": { "type": "string", "enum": [ "RUNNING", "IDLE", "DOWN", "MAINTENANCE", "OFFLINE" ], "description": "What the status means for analytics: RUNNING, IDLE, DOWN, MAINTENANCE or OFFLINE" }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "isDefault": { "description": "The status new SSUs start in (one per company)", "type": "boolean" }, "sortOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "name", "category" ], "additionalProperties": false } }, "reasonCodes": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "downtime", "failure_problem", "failure_cause", "failure_remedy", "scrap", "adjustment" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "code": { "description": "Short code; with the kind, the key (else the label)", "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "parent": { "description": "Code (or label) of a reason of the same kind this one refines", "type": "string" }, "sortOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "isActive": { "type": "boolean" } }, "required": [ "kind", "label" ], "additionalProperties": false } }, "workCenters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" } }, "required": [ "name" ], "additionalProperties": false } }, "sites": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company. In a factory, a site is a floor or area" }, "address": { "description": "Full address. Used when the site is created; not changed afterwards", "type": "string", "maxLength": 500 }, "notes": { "type": [ "string", "null" ] }, "isActive": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "storageUnits": { "description": "Units of the site's own store (each SSU also gets its own unit automatically; those aren't listed)", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique within its site or warehouse" }, "description": { "description": "Where it is and what it holds (aisle, rack, …); its map position comes from the site's address", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "name" ], "additionalProperties": false } }, "ssus": { "description": "Machines, lines and other units on this site, as a tree", "type": "array", "items": { "$ref": "#/$defs/__schema0" } } }, "required": [ "name" ], "additionalProperties": false } }, "warehouses": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "description": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "storageUnits": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique within its site or warehouse" }, "description": { "description": "Where it is and what it holds (aisle, rack, …); its map position comes from the site's address", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "name" ], "additionalProperties": false } } }, "required": [ "name" ], "additionalProperties": false } }, "productCategories": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "description": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "parent": { "description": "Name of the category this one belongs to", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "isActive": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "vendors": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" } }, "required": [ "name" ], "additionalProperties": false } }, "products": { "description": "Products by SKU, with their vendors, recipe and stock policies. No prices or costs", "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The product's key: unique in the company (case-insensitive)" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "itemClass": { "description": "raw, wip, finished, operations (consumables, tools) or spare_part (machine spares)", "type": "string", "enum": [ "raw", "wip", "finished", "operations", "spare_part" ] }, "tracking": { "description": "none, lot or serial", "type": "string", "enum": [ "none", "lot", "serial" ] }, "unitOfMeasurement": { "description": "Stock unit: pcs, kg, g, lb, l, ml, oz, m, cm, mm, yd, ft or in (new products: pcs)", "type": "string", "maxLength": 32 }, "purchasingUnitOfMeasurement": { "description": "The unit it's bought in (new products: the stock unit)", "type": "string", "maxLength": 32 }, "packageQuantity": { "description": "Stock units in one purchasing unit", "type": "number", "exclusiveMinimum": 0 }, "brand": { "description": "Brand name (created if new)", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "category": { "description": "Category name (from productCategories, or one the company has)", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "color": { "description": "Color code used on the floor (bins, labels)", "anyOf": [ { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, { "type": "null" } ] }, "codeType": { "description": "How the SKU is printed as a barcode", "anyOf": [ { "type": "string", "enum": [ "1d", "2d", "qr", "serial" ] }, { "type": "null" } ] }, "tags": { "description": "The product's full set of tags", "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "isActive": { "type": "boolean" }, "vendors": { "description": "Who supplies it. Bought products only: a product with vendors can't have a recipe", "type": "array", "items": { "type": "object", "properties": { "vendor": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Vendor name (from vendors, or one the company has)" }, "vendorSku": { "description": "The vendor's own part number", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "leadTimeDays": { "description": "Order-to-receipt days. When set, reorder uses it instead of the observed lead time", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "priority": { "description": "1 = preferred vendor", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, { "type": "null" } ] }, "code": { "description": "Barcode on the vendor's packaging", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "codeType": { "anyOf": [ { "type": "string", "enum": [ "1d", "2d", "qr", "serial" ] }, { "type": "null" } ] } }, "required": [ "vendor" ], "additionalProperties": false } }, "recipe": { "description": "The full recipe (bill of materials): what one unit consumes. Made products only", "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 255, "description": "SKU of the component (from products, or one the company has)" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "How many one unit of the product consumes" } }, "required": [ "sku", "quantity" ], "additionalProperties": false } }, "stockPolicies": { "description": "Minimums and reorder rules, per site or warehouse", "type": "array", "items": { "type": "object", "properties": { "storage": { "description": "Site or warehouse name the policy applies to; leave out for the whole company", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "minQty": { "type": "number", "minimum": 0, "description": "Reorder when goods on hand fall below this" }, "maxQty": { "description": "Order up to this", "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "reorderQty": { "description": "Fixed quantity to order", "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "null" } ] }, "safetyDays": { "description": "Days of consumption added to the lead time when computing the reorder point", "type": "number", "minimum": 0 } }, "required": [ "minQty" ], "additionalProperties": false } }, "changeover": { "description": "Checklists for a machine changeover: `setup` when this product comes onto a machine, `teardown` when it leaves. Fields as the dashboard stores them: { id, type, title }", "anyOf": [ { "type": "object", "properties": { "setup": { "type": "array", "items": {} }, "teardown": { "type": "array", "items": {} } }, "required": [ "setup", "teardown" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "sku", "name" ], "additionalProperties": false } }, "parameterSets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "parameters": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 255 }, "value": { "type": [ "string", "number" ] }, "uom": { "type": "string", "maxLength": 32 }, "min": { "type": "number" }, "max": { "type": "number" } }, "required": [ "key", "value" ], "additionalProperties": false }, "description": "The machine settings of the released version. A change cuts a new version and releases it; work orders already released keep theirs" } }, "required": [ "name", "parameters" ], "additionalProperties": false } }, "taskTypes": { "description": "Kinds of work, each with its form, SLAs and gates. People (default assignee, skills) come later", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "color": { "type": "string", "maxLength": 32 }, "isQuote": { "type": "boolean" }, "isUserGenerated": { "description": "People can create these tasks from the mobile app", "type": "boolean" }, "isRemote": { "description": "Done without visiting a site", "type": "boolean" }, "isInventory": { "description": "Moves stock (from / to storage, bin, products)", "type": "boolean" }, "isDataRequest": { "description": "Asks a partner company for data", "type": "boolean" }, "defaultUseTransit": { "description": "Inventory moves go through the transit bin", "type": "boolean" }, "requiresFailureCoding": { "description": "Can't complete without problem / cause / remedy codes (maintenance)", "type": "boolean" }, "createdTaskAsReady": { "type": "boolean" }, "useSubmittedStatus": { "description": "Completion goes through 'submitted' for review", "type": "boolean" }, "allowFieldTakeover": { "type": "boolean" }, "recurrenceHours": { "description": "Completing a task schedules the next one this many hours later (time-based PM); 0 = off", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ssuStatusOnOpen": { "description": "SSU status set when a task of this type opens", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "ssuStatusOnComplete": { "description": "SSU status set when it completes", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "workCenter": { "description": "For production operations: the work center that runs it", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "product": { "description": "For production operations: SKU of the product it makes", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "outputStorageUnit": { "description": "Where its output goes: \" / \"", "type": [ "string", "null" ] }, "parameterSet": { "description": "Machine parameters shown at the point of work", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "setupMinutes": { "description": "Standard changeover minutes", "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "runMinutesPerUnit": { "description": "Standard run minutes per unit", "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "minRank": { "description": "Lowest rank that may do it (0 = anyone)", "type": "integer", "minimum": 0, "maximum": 5 }, "team": { "description": "The team whose members see and take its tasks", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "defaultAssignee": { "description": "Email of the person new tasks go to", "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "defaultSubcontractor": { "description": "Email of the subcontractor new tasks go to", "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "requiredSkill": { "description": "Skill needed to do it", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "slas": { "description": "Due time per priority", "type": "array", "items": { "type": "object", "properties": { "priority": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } ], "description": "Priority name, or its level where names repeat" }, "hours": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "priority", "hours" ], "additionalProperties": false } }, "gates": { "description": "Rules a task must meet to move into a status (stage gates); [] removes them", "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "open", "preparation", "ready", "dispatched", "submitted", "incomplete", "done", "declined" ], "description": "The gate applies when a task moves into this status" }, "requiredFields": { "description": "Form field titles that must be filled", "type": "array", "items": { "type": "string" } }, "requiredSignature": { "description": "A signature field must be signed", "type": "boolean" }, "allowedPermissionGroups": { "description": "Only members of these permission groups may make the move", "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "requiredReferences": { "description": "Reference types that must be attached", "type": "array", "items": { "type": "string" } } }, "required": [ "status" ], "additionalProperties": false } }, "form": { "description": "The task's form, in order. Replaces the whole form when given", "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The question; also how gates name the field" }, "type": { "type": "string", "enum": [ "text", "short_text", "number", "checkbox", "select", "datetime", "camera", "signature", "location", "qr", "segment", "products", "storage", "bin", "ssus", "ssu_status", "tag_chooser", "tags", "list", "target_time" ] }, "required": { "type": "boolean" }, "options": { "description": "Type-specific settings, as the Mobile Builder stores them: select → [{ \"id\": \"1\", \"title\": \"Pass\", \"type\": \"select\" }, …]; number → [{ \"id\": \"config\", \"uom\": \"mm\", \"target\": 10, \"lsl\": 9.8, \"usl\": 10.2, \"decimals\": 2 }]. Copy the shape from an export", "type": "array", "items": {} } }, "required": [ "title", "type" ], "additionalProperties": false } } }, "required": [ "name" ], "additionalProperties": false } }, "routings": { "description": "Step sequences that work orders follow", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "product": { "description": "SKU of the product it makes (set when created)", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "steps": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "taskType": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The operation's task type" }, "blocksNext": { "description": "A gate: later steps wait for this one when the work order is released", "type": "boolean" } }, "required": [ "name", "taskType" ], "additionalProperties": false }, "description": "The released version's steps, in order. A change cuts a new version and releases it; released work orders keep theirs" } }, "required": [ "name", "steps" ], "additionalProperties": false } }, "machineData": { "description": "Per machine: signals, meters, condition rules and spare parts", "type": "array", "items": { "type": "object", "properties": { "ssu": { "type": "string", "minLength": 1, "description": "The machine's path: \"Site / Parent / Name\"" }, "signals": { "description": "Signals the machine reports: declared ahead of time, or annotated once they arrive. Never removed", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The signal's key as the machine connector reports it" }, "kind": { "type": "string", "enum": [ "state", "counter", "gauge" ], "description": "state (running / stopped / …), counter or gauge" }, "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "uom": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "isMeter": { "description": "A counter that accumulates into a meter (usage-based PM)", "type": "boolean" }, "isRunState": { "description": "The state signal downtime detection reads (one per machine)", "type": "boolean" }, "runningValue": { "description": "The run-state value that means running", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "key", "kind" ], "additionalProperties": false } }, "meters": { "description": "Manual meters (hours, cycles read by people). Signal-fed meters come from signals marked isMeter", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 255 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "uom": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "key", "name" ], "additionalProperties": false } }, "conditionRules": { "description": "Condition-based maintenance: open a task when a value crosses a limit or a meter advances", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique on this machine" }, "mode": { "description": "threshold: a signal crosses a limit; meter_delta: every N units of a meter", "type": "string", "enum": [ "threshold", "meter_delta" ] }, "signal": { "type": "string", "minLength": 1, "description": "Signal key (threshold) or meter key (meter_delta)" }, "operator": { "description": "threshold mode: above (gt) or below (lt)", "type": "string", "enum": [ "gt", "lt" ] }, "threshold": { "type": "number", "description": "The limit, or the interval in meter units" }, "taskType": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The task type of the task it opens" }, "cooldownHours": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "enabled": { "type": "boolean" } }, "required": [ "name", "signal", "threshold", "taskType" ], "additionalProperties": false } }, "spareParts": { "description": "The machine's spare parts, by product SKU", "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 255 }, "quantity": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "sku", "quantity" ], "additionalProperties": false } } }, "required": [ "ssu" ], "additionalProperties": false } }, "flows": { "description": "Automations: a task's status change creates the next task", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "startsWith": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The task type that starts the flow (set when the flow is created; one flow per type)" }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "taskType": { "type": "string", "minLength": 1, "maxLength": 255 }, "x": { "description": "Position on the canvas", "type": "number" }, "y": { "type": "number" }, "inheritAssignee": { "description": "Tasks it creates take the triggering task's assignees", "type": "boolean" } }, "required": [ "taskType" ], "additionalProperties": false }, "description": "The task types on the canvas" }, "edges": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Task type whose status change triggers" }, "to": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Task type of the task created" }, "onStatus": { "type": "string", "enum": [ "open", "preparation", "ready", "dispatched", "submitted", "incomplete", "done", "declined" ], "description": "The status that triggers it" } }, "required": [ "from", "to", "onStatus" ], "additionalProperties": false }, "description": "When a task of `from` reaches `onStatus`, a task of `to` is created" } }, "required": [ "name", "startsWith", "nodes", "edges" ], "additionalProperties": false } }, "issues": { "description": "Issue reports people can file (from the app or a QR code)", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company: what people pick when they report" }, "taskType": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The task type of the task a report opens" }, "priority": { "description": "Priority name, or its level", "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } ] }, "form": { "description": "The report form, in order. Replaces the whole form", "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The question; also how gates name the field" }, "type": { "type": "string", "enum": [ "text", "short_text", "number", "checkbox", "select", "datetime", "camera", "signature", "location", "qr", "segment", "products", "storage", "bin", "ssus", "ssu_status", "tag_chooser", "tags", "list", "target_time" ] }, "required": { "type": "boolean" }, "options": { "description": "Type-specific settings, as the Mobile Builder stores them: select → [{ \"id\": \"1\", \"title\": \"Pass\", \"type\": \"select\" }, …]; number → [{ \"id\": \"config\", \"uom\": \"mm\", \"target\": 10, \"lsl\": 9.8, \"usl\": 10.2, \"decimals\": 2 }]. Copy the shape from an export", "type": "array", "items": {} } }, "required": [ "title", "type" ], "additionalProperties": false } } }, "required": [ "name", "taskType" ], "additionalProperties": false } }, "permissionGroups": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "color": { "type": "string", "maxLength": 32 }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "tasks:view_all", "tasks:view_my_teams", "tasks:view_pre_active", "tasks:create", "tasks:delete", "tasks:reassign", "tasks:change_status_mobile", "task_types:view", "task_types:manage", "mobile_builder:view", "mobile_builder:manage", "flows:view", "flows:manage", "clients:view", "clients:manage", "geographic:view", "geographic:manage", "personnel:view", "personnel:manage", "subcontractors:view", "subcontractors:manage", "users:view", "users:manage", "access_requests:approve", "permissions:view", "permissions:manage", "settings:view", "settings:manage", "api_keys:view", "api_keys:manage", "webhooks:manage", "audit_logs:view", "data:export", "data:import", "products:view", "products:manage", "inventory:view", "inventory:manage", "inventory:adjust", "inventory:receive", "production:view", "production:manage", "work_orders:release", "machine_data:view", "machine_data:manage", "maintenance:view", "maintenance:manage", "quality:view", "quality:manage", "ncr:disposition", "documents:view", "documents:manage", "documents:publish", "insights:view", "handoffs:send", "partner_data:request", "partner_data:release", "ai_guidance:manage" ] }, "description": "Every permission the group grants (area:verb). The full set: listing replaces it" } }, "required": [ "name", "permissions" ], "additionalProperties": false } }, "roles": { "description": "What people are; each role grants one permission group", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company: what someone is (Technician, Dispatcher, Admin, …)" }, "permissionGroup": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The one permission group the role grants" }, "color": { "type": "string", "maxLength": 32 }, "isOperator": { "type": "boolean" }, "isWarehouse": { "type": "boolean" }, "isDefault": { "type": "boolean" } }, "required": [ "name", "permissionGroup" ], "additionalProperties": false } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company (case-insensitive)" }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" } }, "required": [ "name" ], "additionalProperties": false } }, "skills": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "description": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] } }, "required": [ "name" ], "additionalProperties": false } }, "people": { "description": "Users already in the company, by email: their roles, teams, skills. Specs never invite", "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "A user already in the company: specs never invite anyone" }, "roles": { "description": "All of the person's roles (at least one): their permissions are the union", "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "teams": { "description": "All of the person's teams", "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "skills": { "description": "The person's skill certifications", "type": "array", "items": { "type": "object", "properties": { "skill": { "type": "string", "minLength": 1, "maxLength": 255 }, "certifiedAt": { "description": "ISO date", "type": "string" }, "expiresAt": { "description": "ISO date; null = doesn't expire", "type": [ "string", "null" ] } }, "required": [ "skill" ], "additionalProperties": false } }, "rank": { "type": "integer", "minimum": 0, "maximum": 5 }, "color": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ] }, "isActive": { "type": "boolean" } }, "required": [ "email" ], "additionalProperties": false } }, "subcontractors": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Unique in the company" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "companyName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "roles": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "rank": { "type": "integer", "minimum": 0, "maximum": 5 }, "color": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ] }, "isActive": { "type": "boolean" }, "expirationDate": { "description": "ISO date their engagement ends", "type": [ "string", "null" ] }, "address": { "description": "Full address. Used when created; not changed afterwards", "type": "string", "maxLength": 500 } }, "required": [ "email", "name" ], "additionalProperties": false } }, "inspectionPlans": { "description": "Which receipts or products must be inspected, and how", "type": "array", "items": { "type": "object", "properties": { "appliesTo": { "type": "string", "maxLength": 255, "description": "When it applies: receiving (incoming goods) or in_process" }, "product": { "description": "SKU of the product it covers", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "vendor": { "description": "Vendor it covers", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "taskType": { "description": "The inspection task type", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "samplingRule": { "description": "How many to inspect, e.g. { \"mode\": \"sample\", \"sampleSize\": 5 } or { \"mode\": \"all\" }", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "enabled": { "type": "boolean" } }, "required": [ "appliesTo" ], "additionalProperties": false } }, "guidance": { "description": "What the company tells every AI agent: company-wide and on specific machines, work centers, products, task types", "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string", "enum": [ "company", "ssu", "work_center", "product", "task_type" ] }, "ref": { "description": "Which one (not for company): an SSU path (\"Site / Line / Machine\"), a work center name, a product SKU, a task type name", "type": "string" }, "body": { "type": "string", "minLength": 1, "description": "What every agent should know (company: up to 4000 characters; one subject: 1000)" }, "thresholds": { "description": "stopMinutes: a stop longer than this matters; scrapPercent: scrap above this matters", "type": "object", "properties": { "stopMinutes": { "type": "number", "exclusiveMinimum": 0 }, "scrapPercent": { "type": "number", "minimum": 0, "maximum": 100 } }, "additionalProperties": false } }, "required": [ "subject", "body" ], "additionalProperties": false } } }, "required": [ "version" ], "additionalProperties": false, "description": "The factory spec (export one with config.export to see the shape)" }, "prune": { "description": "Also remove what the spec leaves out of the sections it includes. Records with history (sites, SSUs, reason codes, products) are deactivated, not deleted; vendors, categories, task types and routings are removed only when nothing uses them; parameter sets are never removed. REST only", "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } }, "required": [ "spec" ], "$defs": { "__schema0": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique among its siblings: the SSU's path (site / parent / … / name) is its key" }, "status": { "description": "SSU status name (from ssuStatuses, or one the company has)", "type": "string", "minLength": 1, "maxLength": 255 }, "workCenter": { "description": "Work center name", "type": "string", "minLength": 1, "maxLength": 255 }, "criticality": { "description": "1 (low) to 5 (critical)", "type": "integer", "minimum": 1, "maximum": 5 }, "assetClass": { "description": "Free-form grouping, e.g. CNC, press, gauge", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "make": { "description": "Machine make, from the global machine catalog (factories only); existing spellings are reused", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "model": { "description": "Machine model of that make (needs a make)", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "sku": { "description": "Model-level SKU / part number (not a serial number)", "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "icon": { "type": "string", "enum": [ "cpu", "settings-2", "factory", "flame", "bot", "wrench", "fan", "package", "gauge" ] }, "isActive": { "type": "boolean" }, "isDefault": { "description": "The site's default SSU", "type": "boolean" }, "children": { "description": "Components (sub-assemblies) of this SSU", "type": "array", "items": { "$ref": "#/$defs/__schema0" } } }, "required": [ "name" ], "additionalProperties": false } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "complete": { "type": "boolean" }, "applied": { "type": "array", "items": { "type": "object", "properties": { "section": { "type": "string", "enum": [ "settings", "ssuStatuses", "reasonCodes", "workCenters", "sites", "ssus", "siteStorage", "warehouses", "warehouseStorage", "productCategories", "vendors", "products", "productVendors", "recipes", "stockPolicies", "parameterSets", "taskTypes", "forms", "slas", "gates", "routings", "signals", "meters", "conditionRules", "spareParts", "flows", "issues", "inspectionPlans", "permissionGroups", "roles", "teams", "skills", "people", "subcontractors", "guidance" ] }, "key": { "type": "string" }, "action": { "type": "string", "enum": [ "create", "update", "unchanged", "prune", "extra" ] } }, "required": [ "section", "key", "action" ], "additionalProperties": false } }, "failed": { "type": "object", "properties": { "section": { "type": "string", "enum": [ "settings", "ssuStatuses", "reasonCodes", "workCenters", "sites", "ssus", "siteStorage", "warehouses", "warehouseStorage", "productCategories", "vendors", "products", "productVendors", "recipes", "stockPolicies", "parameterSets", "taskTypes", "forms", "slas", "gates", "routings", "signals", "meters", "conditionRules", "spareParts", "flows", "issues", "inspectionPlans", "permissionGroups", "roles", "teams", "skills", "people", "subcontractors", "guidance" ] }, "key": { "type": "string" }, "action": { "type": "string", "enum": [ "create", "update", "unchanged", "prune", "extra" ] }, "error": { "type": "string" } }, "required": [ "section", "key", "action", "error" ], "additionalProperties": false }, "skipped": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Changes not attempted after a failure" } }, "required": [ "complete", "applied", "skipped" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "config.apply", "x-eightyone-permission": "settings:manage or task_types:manage or clients:manage or inventory:manage or products:manage or production:manage or mobile_builder:manage or machine_data:manage or maintenance:manage or flows:manage or quality:manage or permissions:manage or personnel:manage or subcontractors:manage or ai_guidance:manage", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "unsupported" } }, "/api/v1/config/export": { "get": { "operationId": "config.export", "summary": "Export the factory setup", "description": "The company's setup as a factory spec: settings, SSU statuses, reason codes, work centers, sites with their storage units and SSU trees, warehouses, product categories, vendors, products by SKU with their vendors, recipe and stock policies, parameter sets, task types with their forms, SLAs and gates, routings, per-machine signals, meters, condition rules and spare parts, flows, issue reports, inspection plans, and people (permission groups, roles, teams, skills, existing people by email, subcontractors). Everything is referenced by name, so the spec can be applied to another company as a template. Start here before changing setup: edit the export, then config.plan and config.apply.\n\nPermission: `member`.", "tags": [ "Commissioning" ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "settings": { "type": "object", "properties": { "mobileColor": { "type": [ "string", "null" ] }, "polygonRadius": { "description": "Geofence radius in meters", "type": [ "number", "null" ] }, "dueDateReminderDays": { "description": "0 = off", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "subcontractorExpirationReminderDays": { "description": "0 = off", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "createdTaskAsReady": { "type": "boolean" }, "useSubmittedStatus": { "type": "boolean" }, "kittingAlwaysGenerate": { "type": "boolean" }, "defaultTaskView": { "type": [ "string", "null" ] }, "additionalLanguages": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "assigneePriorityOrder": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "productionOutputStorageUnit": { "description": "Where finished production goes: \" / \"", "type": "string" }, "ncrTaskType": { "description": "Task type used for non-conformance reports (NCRs)", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "kittingTaskType": { "description": "Task type used for kitting work orders", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "documentApprovalTaskType": { "description": "Task type used to approve documents", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "ecnTaskType": { "description": "Task type used for engineering change notices", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] } }, "additionalProperties": false }, "ssuStatuses": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "category": { "type": "string", "enum": [ "RUNNING", "IDLE", "DOWN", "MAINTENANCE", "OFFLINE" ], "description": "What the status means for analytics: RUNNING, IDLE, DOWN, MAINTENANCE or OFFLINE" }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "isDefault": { "description": "The status new SSUs start in (one per company)", "type": "boolean" }, "sortOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "name", "category" ], "additionalProperties": false } }, "reasonCodes": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "downtime", "failure_problem", "failure_cause", "failure_remedy", "scrap", "adjustment" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "code": { "description": "Short code; with the kind, the key (else the label)", "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "parent": { "description": "Code (or label) of a reason of the same kind this one refines", "type": "string" }, "sortOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "isActive": { "type": "boolean" } }, "required": [ "kind", "label" ], "additionalProperties": false } }, "workCenters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" } }, "required": [ "name" ], "additionalProperties": false } }, "sites": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company. In a factory, a site is a floor or area" }, "address": { "description": "Full address. Used when the site is created; not changed afterwards", "type": "string", "maxLength": 500 }, "notes": { "type": [ "string", "null" ] }, "isActive": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "storageUnits": { "description": "Units of the site's own store (each SSU also gets its own unit automatically; those aren't listed)", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique within its site or warehouse" }, "description": { "description": "Where it is and what it holds (aisle, rack, …); its map position comes from the site's address", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "name" ], "additionalProperties": false } }, "ssus": { "description": "Machines, lines and other units on this site, as a tree", "type": "array", "items": { "$ref": "#/$defs/__schema0" } } }, "required": [ "name" ], "additionalProperties": false } }, "warehouses": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "description": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "storageUnits": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique within its site or warehouse" }, "description": { "description": "Where it is and what it holds (aisle, rack, …); its map position comes from the site's address", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "name" ], "additionalProperties": false } } }, "required": [ "name" ], "additionalProperties": false } }, "productCategories": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "description": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "parent": { "description": "Name of the category this one belongs to", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "isActive": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "vendors": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" } }, "required": [ "name" ], "additionalProperties": false } }, "products": { "description": "Products by SKU, with their vendors, recipe and stock policies. No prices or costs", "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The product's key: unique in the company (case-insensitive)" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "itemClass": { "description": "raw, wip, finished, operations (consumables, tools) or spare_part (machine spares)", "type": "string", "enum": [ "raw", "wip", "finished", "operations", "spare_part" ] }, "tracking": { "description": "none, lot or serial", "type": "string", "enum": [ "none", "lot", "serial" ] }, "unitOfMeasurement": { "description": "Stock unit: pcs, kg, g, lb, l, ml, oz, m, cm, mm, yd, ft or in (new products: pcs)", "type": "string", "maxLength": 32 }, "purchasingUnitOfMeasurement": { "description": "The unit it's bought in (new products: the stock unit)", "type": "string", "maxLength": 32 }, "packageQuantity": { "description": "Stock units in one purchasing unit", "type": "number", "exclusiveMinimum": 0 }, "brand": { "description": "Brand name (created if new)", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "category": { "description": "Category name (from productCategories, or one the company has)", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "color": { "description": "Color code used on the floor (bins, labels)", "anyOf": [ { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, { "type": "null" } ] }, "codeType": { "description": "How the SKU is printed as a barcode", "anyOf": [ { "type": "string", "enum": [ "1d", "2d", "qr", "serial" ] }, { "type": "null" } ] }, "tags": { "description": "The product's full set of tags", "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "isActive": { "type": "boolean" }, "vendors": { "description": "Who supplies it. Bought products only: a product with vendors can't have a recipe", "type": "array", "items": { "type": "object", "properties": { "vendor": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Vendor name (from vendors, or one the company has)" }, "vendorSku": { "description": "The vendor's own part number", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "leadTimeDays": { "description": "Order-to-receipt days. When set, reorder uses it instead of the observed lead time", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "priority": { "description": "1 = preferred vendor", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, { "type": "null" } ] }, "code": { "description": "Barcode on the vendor's packaging", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "codeType": { "anyOf": [ { "type": "string", "enum": [ "1d", "2d", "qr", "serial" ] }, { "type": "null" } ] } }, "required": [ "vendor" ], "additionalProperties": false } }, "recipe": { "description": "The full recipe (bill of materials): what one unit consumes. Made products only", "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 255, "description": "SKU of the component (from products, or one the company has)" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "How many one unit of the product consumes" } }, "required": [ "sku", "quantity" ], "additionalProperties": false } }, "stockPolicies": { "description": "Minimums and reorder rules, per site or warehouse", "type": "array", "items": { "type": "object", "properties": { "storage": { "description": "Site or warehouse name the policy applies to; leave out for the whole company", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "minQty": { "type": "number", "minimum": 0, "description": "Reorder when goods on hand fall below this" }, "maxQty": { "description": "Order up to this", "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "reorderQty": { "description": "Fixed quantity to order", "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "null" } ] }, "safetyDays": { "description": "Days of consumption added to the lead time when computing the reorder point", "type": "number", "minimum": 0 } }, "required": [ "minQty" ], "additionalProperties": false } }, "changeover": { "description": "Checklists for a machine changeover: `setup` when this product comes onto a machine, `teardown` when it leaves. Fields as the dashboard stores them: { id, type, title }", "anyOf": [ { "type": "object", "properties": { "setup": { "type": "array", "items": {} }, "teardown": { "type": "array", "items": {} } }, "required": [ "setup", "teardown" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "sku", "name" ], "additionalProperties": false } }, "parameterSets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "parameters": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 255 }, "value": { "type": [ "string", "number" ] }, "uom": { "type": "string", "maxLength": 32 }, "min": { "type": "number" }, "max": { "type": "number" } }, "required": [ "key", "value" ], "additionalProperties": false }, "description": "The machine settings of the released version. A change cuts a new version and releases it; work orders already released keep theirs" } }, "required": [ "name", "parameters" ], "additionalProperties": false } }, "taskTypes": { "description": "Kinds of work, each with its form, SLAs and gates. People (default assignee, skills) come later", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "color": { "type": "string", "maxLength": 32 }, "isQuote": { "type": "boolean" }, "isUserGenerated": { "description": "People can create these tasks from the mobile app", "type": "boolean" }, "isRemote": { "description": "Done without visiting a site", "type": "boolean" }, "isInventory": { "description": "Moves stock (from / to storage, bin, products)", "type": "boolean" }, "isDataRequest": { "description": "Asks a partner company for data", "type": "boolean" }, "defaultUseTransit": { "description": "Inventory moves go through the transit bin", "type": "boolean" }, "requiresFailureCoding": { "description": "Can't complete without problem / cause / remedy codes (maintenance)", "type": "boolean" }, "createdTaskAsReady": { "type": "boolean" }, "useSubmittedStatus": { "description": "Completion goes through 'submitted' for review", "type": "boolean" }, "allowFieldTakeover": { "type": "boolean" }, "recurrenceHours": { "description": "Completing a task schedules the next one this many hours later (time-based PM); 0 = off", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ssuStatusOnOpen": { "description": "SSU status set when a task of this type opens", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "ssuStatusOnComplete": { "description": "SSU status set when it completes", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "workCenter": { "description": "For production operations: the work center that runs it", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "product": { "description": "For production operations: SKU of the product it makes", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "outputStorageUnit": { "description": "Where its output goes: \" / \"", "type": [ "string", "null" ] }, "parameterSet": { "description": "Machine parameters shown at the point of work", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "setupMinutes": { "description": "Standard changeover minutes", "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "runMinutesPerUnit": { "description": "Standard run minutes per unit", "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "minRank": { "description": "Lowest rank that may do it (0 = anyone)", "type": "integer", "minimum": 0, "maximum": 5 }, "team": { "description": "The team whose members see and take its tasks", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "defaultAssignee": { "description": "Email of the person new tasks go to", "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "defaultSubcontractor": { "description": "Email of the subcontractor new tasks go to", "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "requiredSkill": { "description": "Skill needed to do it", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "slas": { "description": "Due time per priority", "type": "array", "items": { "type": "object", "properties": { "priority": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } ], "description": "Priority name, or its level where names repeat" }, "hours": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "priority", "hours" ], "additionalProperties": false } }, "gates": { "description": "Rules a task must meet to move into a status (stage gates); [] removes them", "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "open", "preparation", "ready", "dispatched", "submitted", "incomplete", "done", "declined" ], "description": "The gate applies when a task moves into this status" }, "requiredFields": { "description": "Form field titles that must be filled", "type": "array", "items": { "type": "string" } }, "requiredSignature": { "description": "A signature field must be signed", "type": "boolean" }, "allowedPermissionGroups": { "description": "Only members of these permission groups may make the move", "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "requiredReferences": { "description": "Reference types that must be attached", "type": "array", "items": { "type": "string" } } }, "required": [ "status" ], "additionalProperties": false } }, "form": { "description": "The task's form, in order. Replaces the whole form when given", "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The question; also how gates name the field" }, "type": { "type": "string", "enum": [ "text", "short_text", "number", "checkbox", "select", "datetime", "camera", "signature", "location", "qr", "segment", "products", "storage", "bin", "ssus", "ssu_status", "tag_chooser", "tags", "list", "target_time" ] }, "required": { "type": "boolean" }, "options": { "description": "Type-specific settings, as the Mobile Builder stores them: select → [{ \"id\": \"1\", \"title\": \"Pass\", \"type\": \"select\" }, …]; number → [{ \"id\": \"config\", \"uom\": \"mm\", \"target\": 10, \"lsl\": 9.8, \"usl\": 10.2, \"decimals\": 2 }]. Copy the shape from an export", "type": "array", "items": {} } }, "required": [ "title", "type" ], "additionalProperties": false } } }, "required": [ "name" ], "additionalProperties": false } }, "routings": { "description": "Step sequences that work orders follow", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "product": { "description": "SKU of the product it makes (set when created)", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "steps": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "taskType": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The operation's task type" }, "blocksNext": { "description": "A gate: later steps wait for this one when the work order is released", "type": "boolean" } }, "required": [ "name", "taskType" ], "additionalProperties": false }, "description": "The released version's steps, in order. A change cuts a new version and releases it; released work orders keep theirs" } }, "required": [ "name", "steps" ], "additionalProperties": false } }, "machineData": { "description": "Per machine: signals, meters, condition rules and spare parts", "type": "array", "items": { "type": "object", "properties": { "ssu": { "type": "string", "minLength": 1, "description": "The machine's path: \"Site / Parent / Name\"" }, "signals": { "description": "Signals the machine reports: declared ahead of time, or annotated once they arrive. Never removed", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The signal's key as the machine connector reports it" }, "kind": { "type": "string", "enum": [ "state", "counter", "gauge" ], "description": "state (running / stopped / …), counter or gauge" }, "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "uom": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "isMeter": { "description": "A counter that accumulates into a meter (usage-based PM)", "type": "boolean" }, "isRunState": { "description": "The state signal downtime detection reads (one per machine)", "type": "boolean" }, "runningValue": { "description": "The run-state value that means running", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "key", "kind" ], "additionalProperties": false } }, "meters": { "description": "Manual meters (hours, cycles read by people). Signal-fed meters come from signals marked isMeter", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 255 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "uom": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "key", "name" ], "additionalProperties": false } }, "conditionRules": { "description": "Condition-based maintenance: open a task when a value crosses a limit or a meter advances", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique on this machine" }, "mode": { "description": "threshold: a signal crosses a limit; meter_delta: every N units of a meter", "type": "string", "enum": [ "threshold", "meter_delta" ] }, "signal": { "type": "string", "minLength": 1, "description": "Signal key (threshold) or meter key (meter_delta)" }, "operator": { "description": "threshold mode: above (gt) or below (lt)", "type": "string", "enum": [ "gt", "lt" ] }, "threshold": { "type": "number", "description": "The limit, or the interval in meter units" }, "taskType": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The task type of the task it opens" }, "cooldownHours": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "enabled": { "type": "boolean" } }, "required": [ "name", "signal", "threshold", "taskType" ], "additionalProperties": false } }, "spareParts": { "description": "The machine's spare parts, by product SKU", "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 255 }, "quantity": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "sku", "quantity" ], "additionalProperties": false } } }, "required": [ "ssu" ], "additionalProperties": false } }, "flows": { "description": "Automations: a task's status change creates the next task", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "startsWith": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The task type that starts the flow (set when the flow is created; one flow per type)" }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "taskType": { "type": "string", "minLength": 1, "maxLength": 255 }, "x": { "description": "Position on the canvas", "type": "number" }, "y": { "type": "number" }, "inheritAssignee": { "description": "Tasks it creates take the triggering task's assignees", "type": "boolean" } }, "required": [ "taskType" ], "additionalProperties": false }, "description": "The task types on the canvas" }, "edges": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Task type whose status change triggers" }, "to": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Task type of the task created" }, "onStatus": { "type": "string", "enum": [ "open", "preparation", "ready", "dispatched", "submitted", "incomplete", "done", "declined" ], "description": "The status that triggers it" } }, "required": [ "from", "to", "onStatus" ], "additionalProperties": false }, "description": "When a task of `from` reaches `onStatus`, a task of `to` is created" } }, "required": [ "name", "startsWith", "nodes", "edges" ], "additionalProperties": false } }, "issues": { "description": "Issue reports people can file (from the app or a QR code)", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company: what people pick when they report" }, "taskType": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The task type of the task a report opens" }, "priority": { "description": "Priority name, or its level", "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } ] }, "form": { "description": "The report form, in order. Replaces the whole form", "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The question; also how gates name the field" }, "type": { "type": "string", "enum": [ "text", "short_text", "number", "checkbox", "select", "datetime", "camera", "signature", "location", "qr", "segment", "products", "storage", "bin", "ssus", "ssu_status", "tag_chooser", "tags", "list", "target_time" ] }, "required": { "type": "boolean" }, "options": { "description": "Type-specific settings, as the Mobile Builder stores them: select → [{ \"id\": \"1\", \"title\": \"Pass\", \"type\": \"select\" }, …]; number → [{ \"id\": \"config\", \"uom\": \"mm\", \"target\": 10, \"lsl\": 9.8, \"usl\": 10.2, \"decimals\": 2 }]. Copy the shape from an export", "type": "array", "items": {} } }, "required": [ "title", "type" ], "additionalProperties": false } } }, "required": [ "name", "taskType" ], "additionalProperties": false } }, "permissionGroups": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "color": { "type": "string", "maxLength": 32 }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "tasks:view_all", "tasks:view_my_teams", "tasks:view_pre_active", "tasks:create", "tasks:delete", "tasks:reassign", "tasks:change_status_mobile", "task_types:view", "task_types:manage", "mobile_builder:view", "mobile_builder:manage", "flows:view", "flows:manage", "clients:view", "clients:manage", "geographic:view", "geographic:manage", "personnel:view", "personnel:manage", "subcontractors:view", "subcontractors:manage", "users:view", "users:manage", "access_requests:approve", "permissions:view", "permissions:manage", "settings:view", "settings:manage", "api_keys:view", "api_keys:manage", "webhooks:manage", "audit_logs:view", "data:export", "data:import", "products:view", "products:manage", "inventory:view", "inventory:manage", "inventory:adjust", "inventory:receive", "production:view", "production:manage", "work_orders:release", "machine_data:view", "machine_data:manage", "maintenance:view", "maintenance:manage", "quality:view", "quality:manage", "ncr:disposition", "documents:view", "documents:manage", "documents:publish", "insights:view", "handoffs:send", "partner_data:request", "partner_data:release", "ai_guidance:manage" ] }, "description": "Every permission the group grants (area:verb). The full set: listing replaces it" } }, "required": [ "name", "permissions" ], "additionalProperties": false } }, "roles": { "description": "What people are; each role grants one permission group", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company: what someone is (Technician, Dispatcher, Admin, …)" }, "permissionGroup": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The one permission group the role grants" }, "color": { "type": "string", "maxLength": 32 }, "isOperator": { "type": "boolean" }, "isWarehouse": { "type": "boolean" }, "isDefault": { "type": "boolean" } }, "required": [ "name", "permissionGroup" ], "additionalProperties": false } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company (case-insensitive)" }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" } }, "required": [ "name" ], "additionalProperties": false } }, "skills": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "description": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] } }, "required": [ "name" ], "additionalProperties": false } }, "people": { "description": "Users already in the company, by email: their roles, teams, skills. Specs never invite", "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "A user already in the company: specs never invite anyone" }, "roles": { "description": "All of the person's roles (at least one): their permissions are the union", "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "teams": { "description": "All of the person's teams", "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "skills": { "description": "The person's skill certifications", "type": "array", "items": { "type": "object", "properties": { "skill": { "type": "string", "minLength": 1, "maxLength": 255 }, "certifiedAt": { "description": "ISO date", "type": "string" }, "expiresAt": { "description": "ISO date; null = doesn't expire", "type": [ "string", "null" ] } }, "required": [ "skill" ], "additionalProperties": false } }, "rank": { "type": "integer", "minimum": 0, "maximum": 5 }, "color": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ] }, "isActive": { "type": "boolean" } }, "required": [ "email" ], "additionalProperties": false } }, "subcontractors": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Unique in the company" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "companyName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "roles": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "rank": { "type": "integer", "minimum": 0, "maximum": 5 }, "color": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ] }, "isActive": { "type": "boolean" }, "expirationDate": { "description": "ISO date their engagement ends", "type": [ "string", "null" ] }, "address": { "description": "Full address. Used when created; not changed afterwards", "type": "string", "maxLength": 500 } }, "required": [ "email", "name" ], "additionalProperties": false } }, "inspectionPlans": { "description": "Which receipts or products must be inspected, and how", "type": "array", "items": { "type": "object", "properties": { "appliesTo": { "type": "string", "maxLength": 255, "description": "When it applies: receiving (incoming goods) or in_process" }, "product": { "description": "SKU of the product it covers", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "vendor": { "description": "Vendor it covers", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "taskType": { "description": "The inspection task type", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "samplingRule": { "description": "How many to inspect, e.g. { \"mode\": \"sample\", \"sampleSize\": 5 } or { \"mode\": \"all\" }", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "enabled": { "type": "boolean" } }, "required": [ "appliesTo" ], "additionalProperties": false } }, "guidance": { "description": "What the company tells every AI agent: company-wide and on specific machines, work centers, products, task types", "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string", "enum": [ "company", "ssu", "work_center", "product", "task_type" ] }, "ref": { "description": "Which one (not for company): an SSU path (\"Site / Line / Machine\"), a work center name, a product SKU, a task type name", "type": "string" }, "body": { "type": "string", "minLength": 1, "description": "What every agent should know (company: up to 4000 characters; one subject: 1000)" }, "thresholds": { "description": "stopMinutes: a stop longer than this matters; scrapPercent: scrap above this matters", "type": "object", "properties": { "stopMinutes": { "type": "number", "exclusiveMinimum": 0 }, "scrapPercent": { "type": "number", "minimum": 0, "maximum": 100 } }, "additionalProperties": false } }, "required": [ "subject", "body" ], "additionalProperties": false } } }, "required": [ "version" ], "additionalProperties": false, "description": "A company's setup, by name. Sections and fields left out are not touched.", "$defs": { "__schema0": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique among its siblings: the SSU's path (site / parent / … / name) is its key" }, "status": { "description": "SSU status name (from ssuStatuses, or one the company has)", "type": "string", "minLength": 1, "maxLength": 255 }, "workCenter": { "description": "Work center name", "type": "string", "minLength": 1, "maxLength": 255 }, "criticality": { "description": "1 (low) to 5 (critical)", "type": "integer", "minimum": 1, "maximum": 5 }, "assetClass": { "description": "Free-form grouping, e.g. CNC, press, gauge", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "make": { "description": "Machine make, from the global machine catalog (factories only); existing spellings are reused", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "model": { "description": "Machine model of that make (needs a make)", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "sku": { "description": "Model-level SKU / part number (not a serial number)", "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "icon": { "type": "string", "enum": [ "cpu", "settings-2", "factory", "flame", "bot", "wrench", "fan", "package", "gauge" ] }, "isActive": { "type": "boolean" }, "isDefault": { "description": "The site's default SSU", "type": "boolean" }, "children": { "description": "Components (sub-assemblies) of this SSU", "type": "array", "items": { "$ref": "#/$defs/__schema0" } } }, "required": [ "name" ], "additionalProperties": false } } } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "config.export", "x-eightyone-permission": "member", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/config/plan": { "post": { "operationId": "config.plan", "summary": "Preview applying a factory spec", "description": "What config.apply would do, change by change: create, update (with each field's current and new value), unchanged, and extra (in the company but not in the spec). Doesn't change anything. Show this plan to the user before applying.\n\nPermission: `member`.", "tags": [ "Commissioning" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spec": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "settings": { "type": "object", "properties": { "mobileColor": { "type": [ "string", "null" ] }, "polygonRadius": { "description": "Geofence radius in meters", "type": [ "number", "null" ] }, "dueDateReminderDays": { "description": "0 = off", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "subcontractorExpirationReminderDays": { "description": "0 = off", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "createdTaskAsReady": { "type": "boolean" }, "useSubmittedStatus": { "type": "boolean" }, "kittingAlwaysGenerate": { "type": "boolean" }, "defaultTaskView": { "type": [ "string", "null" ] }, "additionalLanguages": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "assigneePriorityOrder": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "productionOutputStorageUnit": { "description": "Where finished production goes: \" / \"", "type": "string" }, "ncrTaskType": { "description": "Task type used for non-conformance reports (NCRs)", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "kittingTaskType": { "description": "Task type used for kitting work orders", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "documentApprovalTaskType": { "description": "Task type used to approve documents", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "ecnTaskType": { "description": "Task type used for engineering change notices", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] } }, "additionalProperties": false }, "ssuStatuses": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "category": { "type": "string", "enum": [ "RUNNING", "IDLE", "DOWN", "MAINTENANCE", "OFFLINE" ], "description": "What the status means for analytics: RUNNING, IDLE, DOWN, MAINTENANCE or OFFLINE" }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "isDefault": { "description": "The status new SSUs start in (one per company)", "type": "boolean" }, "sortOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "name", "category" ], "additionalProperties": false } }, "reasonCodes": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "downtime", "failure_problem", "failure_cause", "failure_remedy", "scrap", "adjustment" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "code": { "description": "Short code; with the kind, the key (else the label)", "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "parent": { "description": "Code (or label) of a reason of the same kind this one refines", "type": "string" }, "sortOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "isActive": { "type": "boolean" } }, "required": [ "kind", "label" ], "additionalProperties": false } }, "workCenters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" } }, "required": [ "name" ], "additionalProperties": false } }, "sites": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company. In a factory, a site is a floor or area" }, "address": { "description": "Full address. Used when the site is created; not changed afterwards", "type": "string", "maxLength": 500 }, "notes": { "type": [ "string", "null" ] }, "isActive": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "storageUnits": { "description": "Units of the site's own store (each SSU also gets its own unit automatically; those aren't listed)", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique within its site or warehouse" }, "description": { "description": "Where it is and what it holds (aisle, rack, …); its map position comes from the site's address", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "name" ], "additionalProperties": false } }, "ssus": { "description": "Machines, lines and other units on this site, as a tree", "type": "array", "items": { "$ref": "#/$defs/__schema0" } } }, "required": [ "name" ], "additionalProperties": false } }, "warehouses": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "description": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "storageUnits": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique within its site or warehouse" }, "description": { "description": "Where it is and what it holds (aisle, rack, …); its map position comes from the site's address", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "name" ], "additionalProperties": false } } }, "required": [ "name" ], "additionalProperties": false } }, "productCategories": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "description": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "parent": { "description": "Name of the category this one belongs to", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "isActive": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "vendors": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" } }, "required": [ "name" ], "additionalProperties": false } }, "products": { "description": "Products by SKU, with their vendors, recipe and stock policies. No prices or costs", "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The product's key: unique in the company (case-insensitive)" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "itemClass": { "description": "raw, wip, finished, operations (consumables, tools) or spare_part (machine spares)", "type": "string", "enum": [ "raw", "wip", "finished", "operations", "spare_part" ] }, "tracking": { "description": "none, lot or serial", "type": "string", "enum": [ "none", "lot", "serial" ] }, "unitOfMeasurement": { "description": "Stock unit: pcs, kg, g, lb, l, ml, oz, m, cm, mm, yd, ft or in (new products: pcs)", "type": "string", "maxLength": 32 }, "purchasingUnitOfMeasurement": { "description": "The unit it's bought in (new products: the stock unit)", "type": "string", "maxLength": 32 }, "packageQuantity": { "description": "Stock units in one purchasing unit", "type": "number", "exclusiveMinimum": 0 }, "brand": { "description": "Brand name (created if new)", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "category": { "description": "Category name (from productCategories, or one the company has)", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "color": { "description": "Color code used on the floor (bins, labels)", "anyOf": [ { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, { "type": "null" } ] }, "codeType": { "description": "How the SKU is printed as a barcode", "anyOf": [ { "type": "string", "enum": [ "1d", "2d", "qr", "serial" ] }, { "type": "null" } ] }, "tags": { "description": "The product's full set of tags", "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "isActive": { "type": "boolean" }, "vendors": { "description": "Who supplies it. Bought products only: a product with vendors can't have a recipe", "type": "array", "items": { "type": "object", "properties": { "vendor": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Vendor name (from vendors, or one the company has)" }, "vendorSku": { "description": "The vendor's own part number", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "leadTimeDays": { "description": "Order-to-receipt days. When set, reorder uses it instead of the observed lead time", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "priority": { "description": "1 = preferred vendor", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, { "type": "null" } ] }, "code": { "description": "Barcode on the vendor's packaging", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "codeType": { "anyOf": [ { "type": "string", "enum": [ "1d", "2d", "qr", "serial" ] }, { "type": "null" } ] } }, "required": [ "vendor" ], "additionalProperties": false } }, "recipe": { "description": "The full recipe (bill of materials): what one unit consumes. Made products only", "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 255, "description": "SKU of the component (from products, or one the company has)" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "How many one unit of the product consumes" } }, "required": [ "sku", "quantity" ], "additionalProperties": false } }, "stockPolicies": { "description": "Minimums and reorder rules, per site or warehouse", "type": "array", "items": { "type": "object", "properties": { "storage": { "description": "Site or warehouse name the policy applies to; leave out for the whole company", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "minQty": { "type": "number", "minimum": 0, "description": "Reorder when goods on hand fall below this" }, "maxQty": { "description": "Order up to this", "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "reorderQty": { "description": "Fixed quantity to order", "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "null" } ] }, "safetyDays": { "description": "Days of consumption added to the lead time when computing the reorder point", "type": "number", "minimum": 0 } }, "required": [ "minQty" ], "additionalProperties": false } }, "changeover": { "description": "Checklists for a machine changeover: `setup` when this product comes onto a machine, `teardown` when it leaves. Fields as the dashboard stores them: { id, type, title }", "anyOf": [ { "type": "object", "properties": { "setup": { "type": "array", "items": {} }, "teardown": { "type": "array", "items": {} } }, "required": [ "setup", "teardown" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "sku", "name" ], "additionalProperties": false } }, "parameterSets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "parameters": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 255 }, "value": { "type": [ "string", "number" ] }, "uom": { "type": "string", "maxLength": 32 }, "min": { "type": "number" }, "max": { "type": "number" } }, "required": [ "key", "value" ], "additionalProperties": false }, "description": "The machine settings of the released version. A change cuts a new version and releases it; work orders already released keep theirs" } }, "required": [ "name", "parameters" ], "additionalProperties": false } }, "taskTypes": { "description": "Kinds of work, each with its form, SLAs and gates. People (default assignee, skills) come later", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "color": { "type": "string", "maxLength": 32 }, "isQuote": { "type": "boolean" }, "isUserGenerated": { "description": "People can create these tasks from the mobile app", "type": "boolean" }, "isRemote": { "description": "Done without visiting a site", "type": "boolean" }, "isInventory": { "description": "Moves stock (from / to storage, bin, products)", "type": "boolean" }, "isDataRequest": { "description": "Asks a partner company for data", "type": "boolean" }, "defaultUseTransit": { "description": "Inventory moves go through the transit bin", "type": "boolean" }, "requiresFailureCoding": { "description": "Can't complete without problem / cause / remedy codes (maintenance)", "type": "boolean" }, "createdTaskAsReady": { "type": "boolean" }, "useSubmittedStatus": { "description": "Completion goes through 'submitted' for review", "type": "boolean" }, "allowFieldTakeover": { "type": "boolean" }, "recurrenceHours": { "description": "Completing a task schedules the next one this many hours later (time-based PM); 0 = off", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ssuStatusOnOpen": { "description": "SSU status set when a task of this type opens", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "ssuStatusOnComplete": { "description": "SSU status set when it completes", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "workCenter": { "description": "For production operations: the work center that runs it", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "product": { "description": "For production operations: SKU of the product it makes", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "outputStorageUnit": { "description": "Where its output goes: \" / \"", "type": [ "string", "null" ] }, "parameterSet": { "description": "Machine parameters shown at the point of work", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "setupMinutes": { "description": "Standard changeover minutes", "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "runMinutesPerUnit": { "description": "Standard run minutes per unit", "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "minRank": { "description": "Lowest rank that may do it (0 = anyone)", "type": "integer", "minimum": 0, "maximum": 5 }, "team": { "description": "The team whose members see and take its tasks", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "defaultAssignee": { "description": "Email of the person new tasks go to", "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "defaultSubcontractor": { "description": "Email of the subcontractor new tasks go to", "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "requiredSkill": { "description": "Skill needed to do it", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "slas": { "description": "Due time per priority", "type": "array", "items": { "type": "object", "properties": { "priority": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } ], "description": "Priority name, or its level where names repeat" }, "hours": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "priority", "hours" ], "additionalProperties": false } }, "gates": { "description": "Rules a task must meet to move into a status (stage gates); [] removes them", "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "open", "preparation", "ready", "dispatched", "submitted", "incomplete", "done", "declined" ], "description": "The gate applies when a task moves into this status" }, "requiredFields": { "description": "Form field titles that must be filled", "type": "array", "items": { "type": "string" } }, "requiredSignature": { "description": "A signature field must be signed", "type": "boolean" }, "allowedPermissionGroups": { "description": "Only members of these permission groups may make the move", "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "requiredReferences": { "description": "Reference types that must be attached", "type": "array", "items": { "type": "string" } } }, "required": [ "status" ], "additionalProperties": false } }, "form": { "description": "The task's form, in order. Replaces the whole form when given", "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The question; also how gates name the field" }, "type": { "type": "string", "enum": [ "text", "short_text", "number", "checkbox", "select", "datetime", "camera", "signature", "location", "qr", "segment", "products", "storage", "bin", "ssus", "ssu_status", "tag_chooser", "tags", "list", "target_time" ] }, "required": { "type": "boolean" }, "options": { "description": "Type-specific settings, as the Mobile Builder stores them: select → [{ \"id\": \"1\", \"title\": \"Pass\", \"type\": \"select\" }, …]; number → [{ \"id\": \"config\", \"uom\": \"mm\", \"target\": 10, \"lsl\": 9.8, \"usl\": 10.2, \"decimals\": 2 }]. Copy the shape from an export", "type": "array", "items": {} } }, "required": [ "title", "type" ], "additionalProperties": false } } }, "required": [ "name" ], "additionalProperties": false } }, "routings": { "description": "Step sequences that work orders follow", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "product": { "description": "SKU of the product it makes (set when created)", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "steps": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "taskType": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The operation's task type" }, "blocksNext": { "description": "A gate: later steps wait for this one when the work order is released", "type": "boolean" } }, "required": [ "name", "taskType" ], "additionalProperties": false }, "description": "The released version's steps, in order. A change cuts a new version and releases it; released work orders keep theirs" } }, "required": [ "name", "steps" ], "additionalProperties": false } }, "machineData": { "description": "Per machine: signals, meters, condition rules and spare parts", "type": "array", "items": { "type": "object", "properties": { "ssu": { "type": "string", "minLength": 1, "description": "The machine's path: \"Site / Parent / Name\"" }, "signals": { "description": "Signals the machine reports: declared ahead of time, or annotated once they arrive. Never removed", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The signal's key as the machine connector reports it" }, "kind": { "type": "string", "enum": [ "state", "counter", "gauge" ], "description": "state (running / stopped / …), counter or gauge" }, "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "uom": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "isMeter": { "description": "A counter that accumulates into a meter (usage-based PM)", "type": "boolean" }, "isRunState": { "description": "The state signal downtime detection reads (one per machine)", "type": "boolean" }, "runningValue": { "description": "The run-state value that means running", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "key", "kind" ], "additionalProperties": false } }, "meters": { "description": "Manual meters (hours, cycles read by people). Signal-fed meters come from signals marked isMeter", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 255 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "uom": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "key", "name" ], "additionalProperties": false } }, "conditionRules": { "description": "Condition-based maintenance: open a task when a value crosses a limit or a meter advances", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique on this machine" }, "mode": { "description": "threshold: a signal crosses a limit; meter_delta: every N units of a meter", "type": "string", "enum": [ "threshold", "meter_delta" ] }, "signal": { "type": "string", "minLength": 1, "description": "Signal key (threshold) or meter key (meter_delta)" }, "operator": { "description": "threshold mode: above (gt) or below (lt)", "type": "string", "enum": [ "gt", "lt" ] }, "threshold": { "type": "number", "description": "The limit, or the interval in meter units" }, "taskType": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The task type of the task it opens" }, "cooldownHours": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "enabled": { "type": "boolean" } }, "required": [ "name", "signal", "threshold", "taskType" ], "additionalProperties": false } }, "spareParts": { "description": "The machine's spare parts, by product SKU", "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 255 }, "quantity": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "sku", "quantity" ], "additionalProperties": false } } }, "required": [ "ssu" ], "additionalProperties": false } }, "flows": { "description": "Automations: a task's status change creates the next task", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "startsWith": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The task type that starts the flow (set when the flow is created; one flow per type)" }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "taskType": { "type": "string", "minLength": 1, "maxLength": 255 }, "x": { "description": "Position on the canvas", "type": "number" }, "y": { "type": "number" }, "inheritAssignee": { "description": "Tasks it creates take the triggering task's assignees", "type": "boolean" } }, "required": [ "taskType" ], "additionalProperties": false }, "description": "The task types on the canvas" }, "edges": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Task type whose status change triggers" }, "to": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Task type of the task created" }, "onStatus": { "type": "string", "enum": [ "open", "preparation", "ready", "dispatched", "submitted", "incomplete", "done", "declined" ], "description": "The status that triggers it" } }, "required": [ "from", "to", "onStatus" ], "additionalProperties": false }, "description": "When a task of `from` reaches `onStatus`, a task of `to` is created" } }, "required": [ "name", "startsWith", "nodes", "edges" ], "additionalProperties": false } }, "issues": { "description": "Issue reports people can file (from the app or a QR code)", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company: what people pick when they report" }, "taskType": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The task type of the task a report opens" }, "priority": { "description": "Priority name, or its level", "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } ] }, "form": { "description": "The report form, in order. Replaces the whole form", "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The question; also how gates name the field" }, "type": { "type": "string", "enum": [ "text", "short_text", "number", "checkbox", "select", "datetime", "camera", "signature", "location", "qr", "segment", "products", "storage", "bin", "ssus", "ssu_status", "tag_chooser", "tags", "list", "target_time" ] }, "required": { "type": "boolean" }, "options": { "description": "Type-specific settings, as the Mobile Builder stores them: select → [{ \"id\": \"1\", \"title\": \"Pass\", \"type\": \"select\" }, …]; number → [{ \"id\": \"config\", \"uom\": \"mm\", \"target\": 10, \"lsl\": 9.8, \"usl\": 10.2, \"decimals\": 2 }]. Copy the shape from an export", "type": "array", "items": {} } }, "required": [ "title", "type" ], "additionalProperties": false } } }, "required": [ "name", "taskType" ], "additionalProperties": false } }, "permissionGroups": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "color": { "type": "string", "maxLength": 32 }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "tasks:view_all", "tasks:view_my_teams", "tasks:view_pre_active", "tasks:create", "tasks:delete", "tasks:reassign", "tasks:change_status_mobile", "task_types:view", "task_types:manage", "mobile_builder:view", "mobile_builder:manage", "flows:view", "flows:manage", "clients:view", "clients:manage", "geographic:view", "geographic:manage", "personnel:view", "personnel:manage", "subcontractors:view", "subcontractors:manage", "users:view", "users:manage", "access_requests:approve", "permissions:view", "permissions:manage", "settings:view", "settings:manage", "api_keys:view", "api_keys:manage", "webhooks:manage", "audit_logs:view", "data:export", "data:import", "products:view", "products:manage", "inventory:view", "inventory:manage", "inventory:adjust", "inventory:receive", "production:view", "production:manage", "work_orders:release", "machine_data:view", "machine_data:manage", "maintenance:view", "maintenance:manage", "quality:view", "quality:manage", "ncr:disposition", "documents:view", "documents:manage", "documents:publish", "insights:view", "handoffs:send", "partner_data:request", "partner_data:release", "ai_guidance:manage" ] }, "description": "Every permission the group grants (area:verb). The full set: listing replaces it" } }, "required": [ "name", "permissions" ], "additionalProperties": false } }, "roles": { "description": "What people are; each role grants one permission group", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company: what someone is (Technician, Dispatcher, Admin, …)" }, "permissionGroup": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The one permission group the role grants" }, "color": { "type": "string", "maxLength": 32 }, "isOperator": { "type": "boolean" }, "isWarehouse": { "type": "boolean" }, "isDefault": { "type": "boolean" } }, "required": [ "name", "permissionGroup" ], "additionalProperties": false } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company (case-insensitive)" }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" } }, "required": [ "name" ], "additionalProperties": false } }, "skills": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "description": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] } }, "required": [ "name" ], "additionalProperties": false } }, "people": { "description": "Users already in the company, by email: their roles, teams, skills. Specs never invite", "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "A user already in the company: specs never invite anyone" }, "roles": { "description": "All of the person's roles (at least one): their permissions are the union", "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "teams": { "description": "All of the person's teams", "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "skills": { "description": "The person's skill certifications", "type": "array", "items": { "type": "object", "properties": { "skill": { "type": "string", "minLength": 1, "maxLength": 255 }, "certifiedAt": { "description": "ISO date", "type": "string" }, "expiresAt": { "description": "ISO date; null = doesn't expire", "type": [ "string", "null" ] } }, "required": [ "skill" ], "additionalProperties": false } }, "rank": { "type": "integer", "minimum": 0, "maximum": 5 }, "color": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ] }, "isActive": { "type": "boolean" } }, "required": [ "email" ], "additionalProperties": false } }, "subcontractors": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Unique in the company" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "companyName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "roles": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "rank": { "type": "integer", "minimum": 0, "maximum": 5 }, "color": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ] }, "isActive": { "type": "boolean" }, "expirationDate": { "description": "ISO date their engagement ends", "type": [ "string", "null" ] }, "address": { "description": "Full address. Used when created; not changed afterwards", "type": "string", "maxLength": 500 } }, "required": [ "email", "name" ], "additionalProperties": false } }, "inspectionPlans": { "description": "Which receipts or products must be inspected, and how", "type": "array", "items": { "type": "object", "properties": { "appliesTo": { "type": "string", "maxLength": 255, "description": "When it applies: receiving (incoming goods) or in_process" }, "product": { "description": "SKU of the product it covers", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "vendor": { "description": "Vendor it covers", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "taskType": { "description": "The inspection task type", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "samplingRule": { "description": "How many to inspect, e.g. { \"mode\": \"sample\", \"sampleSize\": 5 } or { \"mode\": \"all\" }", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "enabled": { "type": "boolean" } }, "required": [ "appliesTo" ], "additionalProperties": false } }, "guidance": { "description": "What the company tells every AI agent: company-wide and on specific machines, work centers, products, task types", "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string", "enum": [ "company", "ssu", "work_center", "product", "task_type" ] }, "ref": { "description": "Which one (not for company): an SSU path (\"Site / Line / Machine\"), a work center name, a product SKU, a task type name", "type": "string" }, "body": { "type": "string", "minLength": 1, "description": "What every agent should know (company: up to 4000 characters; one subject: 1000)" }, "thresholds": { "description": "stopMinutes: a stop longer than this matters; scrapPercent: scrap above this matters", "type": "object", "properties": { "stopMinutes": { "type": "number", "exclusiveMinimum": 0 }, "scrapPercent": { "type": "number", "minimum": 0, "maximum": 100 } }, "additionalProperties": false } }, "required": [ "subject", "body" ], "additionalProperties": false } } }, "required": [ "version" ], "additionalProperties": false, "description": "The factory spec (export one with config.export to see the shape)" }, "prune": { "description": "Also remove what the spec leaves out of the sections it includes. Records with history (sites, SSUs, reason codes, products) are deactivated, not deleted; vendors, categories, task types and routings are removed only when nothing uses them; parameter sets are never removed. REST only", "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } }, "required": [ "spec" ], "$defs": { "__schema0": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique among its siblings: the SSU's path (site / parent / … / name) is its key" }, "status": { "description": "SSU status name (from ssuStatuses, or one the company has)", "type": "string", "minLength": 1, "maxLength": 255 }, "workCenter": { "description": "Work center name", "type": "string", "minLength": 1, "maxLength": 255 }, "criticality": { "description": "1 (low) to 5 (critical)", "type": "integer", "minimum": 1, "maximum": 5 }, "assetClass": { "description": "Free-form grouping, e.g. CNC, press, gauge", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "make": { "description": "Machine make, from the global machine catalog (factories only); existing spellings are reused", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "model": { "description": "Machine model of that make (needs a make)", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "sku": { "description": "Model-level SKU / part number (not a serial number)", "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "icon": { "type": "string", "enum": [ "cpu", "settings-2", "factory", "flame", "bot", "wrench", "fan", "package", "gauge" ] }, "isActive": { "type": "boolean" }, "isDefault": { "description": "The site's default SSU", "type": "boolean" }, "children": { "description": "Components (sub-assemblies) of this SSU", "type": "array", "items": { "$ref": "#/$defs/__schema0" } } }, "required": [ "name" ], "additionalProperties": false } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "problems": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } }, "summary": { "type": "object", "properties": { "create": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "update": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "unchanged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "prune": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "extra": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "create", "update", "unchanged", "prune", "extra" ], "additionalProperties": false }, "changes": { "type": "array", "items": { "type": "object", "properties": { "section": { "type": "string", "enum": [ "settings", "ssuStatuses", "reasonCodes", "workCenters", "sites", "ssus", "siteStorage", "warehouses", "warehouseStorage", "productCategories", "vendors", "products", "productVendors", "recipes", "stockPolicies", "parameterSets", "taskTypes", "forms", "slas", "gates", "routings", "signals", "meters", "conditionRules", "spareParts", "flows", "issues", "inspectionPlans", "permissionGroups", "roles", "teams", "skills", "people", "subcontractors", "guidance" ] }, "key": { "type": "string", "description": "What the change is about, by name: a status, a site, \"Site / Line / Machine\"…" }, "action": { "type": "string", "enum": [ "create", "update", "unchanged", "prune", "extra" ], "description": "extra: exists in the company but not in the spec; left alone unless prune is requested" }, "fields": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "from": {}, "to": {} }, "required": [ "from", "to" ], "additionalProperties": false } }, "blocked": { "description": "Set when you lack the permission for this change", "type": "string" } }, "required": [ "section", "key", "action" ], "additionalProperties": false } } }, "required": [ "valid", "problems", "summary", "changes" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "config.plan", "x-eightyone-permission": "member", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/config/validate": { "post": { "operationId": "config.validate", "summary": "Validate a factory spec", "description": "Checks a spec beyond its schema: duplicate names or SKUs, references to statuses, work centers, reason codes, storage, categories, vendors, SKUs, task types, parameter sets or permission groups that don't exist, ambiguous names, a product both bought and made, gates naming fields the form doesn't have. Doesn't change anything.\n\nPermission: `member`.", "tags": [ "Commissioning" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "spec": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "settings": { "type": "object", "properties": { "mobileColor": { "type": [ "string", "null" ] }, "polygonRadius": { "description": "Geofence radius in meters", "type": [ "number", "null" ] }, "dueDateReminderDays": { "description": "0 = off", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "subcontractorExpirationReminderDays": { "description": "0 = off", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "createdTaskAsReady": { "type": "boolean" }, "useSubmittedStatus": { "type": "boolean" }, "kittingAlwaysGenerate": { "type": "boolean" }, "defaultTaskView": { "type": [ "string", "null" ] }, "additionalLanguages": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "assigneePriorityOrder": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "productionOutputStorageUnit": { "description": "Where finished production goes: \" / \"", "type": "string" }, "ncrTaskType": { "description": "Task type used for non-conformance reports (NCRs)", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "kittingTaskType": { "description": "Task type used for kitting work orders", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "documentApprovalTaskType": { "description": "Task type used to approve documents", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "ecnTaskType": { "description": "Task type used for engineering change notices", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] } }, "additionalProperties": false }, "ssuStatuses": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "category": { "type": "string", "enum": [ "RUNNING", "IDLE", "DOWN", "MAINTENANCE", "OFFLINE" ], "description": "What the status means for analytics: RUNNING, IDLE, DOWN, MAINTENANCE or OFFLINE" }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "isDefault": { "description": "The status new SSUs start in (one per company)", "type": "boolean" }, "sortOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "name", "category" ], "additionalProperties": false } }, "reasonCodes": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "downtime", "failure_problem", "failure_cause", "failure_remedy", "scrap", "adjustment" ] }, "label": { "type": "string", "minLength": 1, "maxLength": 255 }, "code": { "description": "Short code; with the kind, the key (else the label)", "anyOf": [ { "type": "string", "maxLength": 64 }, { "type": "null" } ] }, "parent": { "description": "Code (or label) of a reason of the same kind this one refines", "type": "string" }, "sortOrder": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "isActive": { "type": "boolean" } }, "required": [ "kind", "label" ], "additionalProperties": false } }, "workCenters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" } }, "required": [ "name" ], "additionalProperties": false } }, "sites": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company. In a factory, a site is a floor or area" }, "address": { "description": "Full address. Used when the site is created; not changed afterwards", "type": "string", "maxLength": 500 }, "notes": { "type": [ "string", "null" ] }, "isActive": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "storageUnits": { "description": "Units of the site's own store (each SSU also gets its own unit automatically; those aren't listed)", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique within its site or warehouse" }, "description": { "description": "Where it is and what it holds (aisle, rack, …); its map position comes from the site's address", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "name" ], "additionalProperties": false } }, "ssus": { "description": "Machines, lines and other units on this site, as a tree", "type": "array", "items": { "$ref": "#/$defs/__schema0" } } }, "required": [ "name" ], "additionalProperties": false } }, "warehouses": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "description": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "storageUnits": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique within its site or warehouse" }, "description": { "description": "Where it is and what it holds (aisle, rack, …); its map position comes from the site's address", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "name" ], "additionalProperties": false } } }, "required": [ "name" ], "additionalProperties": false } }, "productCategories": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "description": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "parent": { "description": "Name of the category this one belongs to", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "isActive": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } }, "vendors": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" } }, "required": [ "name" ], "additionalProperties": false } }, "products": { "description": "Products by SKU, with their vendors, recipe and stock policies. No prices or costs", "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The product's key: unique in the company (case-insensitive)" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "itemClass": { "description": "raw, wip, finished, operations (consumables, tools) or spare_part (machine spares)", "type": "string", "enum": [ "raw", "wip", "finished", "operations", "spare_part" ] }, "tracking": { "description": "none, lot or serial", "type": "string", "enum": [ "none", "lot", "serial" ] }, "unitOfMeasurement": { "description": "Stock unit: pcs, kg, g, lb, l, ml, oz, m, cm, mm, yd, ft or in (new products: pcs)", "type": "string", "maxLength": 32 }, "purchasingUnitOfMeasurement": { "description": "The unit it's bought in (new products: the stock unit)", "type": "string", "maxLength": 32 }, "packageQuantity": { "description": "Stock units in one purchasing unit", "type": "number", "exclusiveMinimum": 0 }, "brand": { "description": "Brand name (created if new)", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "category": { "description": "Category name (from productCategories, or one the company has)", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "color": { "description": "Color code used on the floor (bins, labels)", "anyOf": [ { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, { "type": "null" } ] }, "codeType": { "description": "How the SKU is printed as a barcode", "anyOf": [ { "type": "string", "enum": [ "1d", "2d", "qr", "serial" ] }, { "type": "null" } ] }, "tags": { "description": "The product's full set of tags", "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "isActive": { "type": "boolean" }, "vendors": { "description": "Who supplies it. Bought products only: a product with vendors can't have a recipe", "type": "array", "items": { "type": "object", "properties": { "vendor": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Vendor name (from vendors, or one the company has)" }, "vendorSku": { "description": "The vendor's own part number", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "leadTimeDays": { "description": "Order-to-receipt days. When set, reorder uses it instead of the observed lead time", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "priority": { "description": "1 = preferred vendor", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, { "type": "null" } ] }, "code": { "description": "Barcode on the vendor's packaging", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "codeType": { "anyOf": [ { "type": "string", "enum": [ "1d", "2d", "qr", "serial" ] }, { "type": "null" } ] } }, "required": [ "vendor" ], "additionalProperties": false } }, "recipe": { "description": "The full recipe (bill of materials): what one unit consumes. Made products only", "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 255, "description": "SKU of the component (from products, or one the company has)" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "How many one unit of the product consumes" } }, "required": [ "sku", "quantity" ], "additionalProperties": false } }, "stockPolicies": { "description": "Minimums and reorder rules, per site or warehouse", "type": "array", "items": { "type": "object", "properties": { "storage": { "description": "Site or warehouse name the policy applies to; leave out for the whole company", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "minQty": { "type": "number", "minimum": 0, "description": "Reorder when goods on hand fall below this" }, "maxQty": { "description": "Order up to this", "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "reorderQty": { "description": "Fixed quantity to order", "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "null" } ] }, "safetyDays": { "description": "Days of consumption added to the lead time when computing the reorder point", "type": "number", "minimum": 0 } }, "required": [ "minQty" ], "additionalProperties": false } }, "changeover": { "description": "Checklists for a machine changeover: `setup` when this product comes onto a machine, `teardown` when it leaves. Fields as the dashboard stores them: { id, type, title }", "anyOf": [ { "type": "object", "properties": { "setup": { "type": "array", "items": {} }, "teardown": { "type": "array", "items": {} } }, "required": [ "setup", "teardown" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "sku", "name" ], "additionalProperties": false } }, "parameterSets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "parameters": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 255 }, "value": { "type": [ "string", "number" ] }, "uom": { "type": "string", "maxLength": 32 }, "min": { "type": "number" }, "max": { "type": "number" } }, "required": [ "key", "value" ], "additionalProperties": false }, "description": "The machine settings of the released version. A change cuts a new version and releases it; work orders already released keep theirs" } }, "required": [ "name", "parameters" ], "additionalProperties": false } }, "taskTypes": { "description": "Kinds of work, each with its form, SLAs and gates. People (default assignee, skills) come later", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "color": { "type": "string", "maxLength": 32 }, "isQuote": { "type": "boolean" }, "isUserGenerated": { "description": "People can create these tasks from the mobile app", "type": "boolean" }, "isRemote": { "description": "Done without visiting a site", "type": "boolean" }, "isInventory": { "description": "Moves stock (from / to storage, bin, products)", "type": "boolean" }, "isDataRequest": { "description": "Asks a partner company for data", "type": "boolean" }, "defaultUseTransit": { "description": "Inventory moves go through the transit bin", "type": "boolean" }, "requiresFailureCoding": { "description": "Can't complete without problem / cause / remedy codes (maintenance)", "type": "boolean" }, "createdTaskAsReady": { "type": "boolean" }, "useSubmittedStatus": { "description": "Completion goes through 'submitted' for review", "type": "boolean" }, "allowFieldTakeover": { "type": "boolean" }, "recurrenceHours": { "description": "Completing a task schedules the next one this many hours later (time-based PM); 0 = off", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "ssuStatusOnOpen": { "description": "SSU status set when a task of this type opens", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "ssuStatusOnComplete": { "description": "SSU status set when it completes", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "workCenter": { "description": "For production operations: the work center that runs it", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "product": { "description": "For production operations: SKU of the product it makes", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "outputStorageUnit": { "description": "Where its output goes: \" / \"", "type": [ "string", "null" ] }, "parameterSet": { "description": "Machine parameters shown at the point of work", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "setupMinutes": { "description": "Standard changeover minutes", "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "runMinutesPerUnit": { "description": "Standard run minutes per unit", "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "minRank": { "description": "Lowest rank that may do it (0 = anyone)", "type": "integer", "minimum": 0, "maximum": 5 }, "team": { "description": "The team whose members see and take its tasks", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "defaultAssignee": { "description": "Email of the person new tasks go to", "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "defaultSubcontractor": { "description": "Email of the subcontractor new tasks go to", "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "requiredSkill": { "description": "Skill needed to do it", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "slas": { "description": "Due time per priority", "type": "array", "items": { "type": "object", "properties": { "priority": { "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } ], "description": "Priority name, or its level where names repeat" }, "hours": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "priority", "hours" ], "additionalProperties": false } }, "gates": { "description": "Rules a task must meet to move into a status (stage gates); [] removes them", "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "open", "preparation", "ready", "dispatched", "submitted", "incomplete", "done", "declined" ], "description": "The gate applies when a task moves into this status" }, "requiredFields": { "description": "Form field titles that must be filled", "type": "array", "items": { "type": "string" } }, "requiredSignature": { "description": "A signature field must be signed", "type": "boolean" }, "allowedPermissionGroups": { "description": "Only members of these permission groups may make the move", "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "requiredReferences": { "description": "Reference types that must be attached", "type": "array", "items": { "type": "string" } } }, "required": [ "status" ], "additionalProperties": false } }, "form": { "description": "The task's form, in order. Replaces the whole form when given", "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The question; also how gates name the field" }, "type": { "type": "string", "enum": [ "text", "short_text", "number", "checkbox", "select", "datetime", "camera", "signature", "location", "qr", "segment", "products", "storage", "bin", "ssus", "ssu_status", "tag_chooser", "tags", "list", "target_time" ] }, "required": { "type": "boolean" }, "options": { "description": "Type-specific settings, as the Mobile Builder stores them: select → [{ \"id\": \"1\", \"title\": \"Pass\", \"type\": \"select\" }, …]; number → [{ \"id\": \"config\", \"uom\": \"mm\", \"target\": 10, \"lsl\": 9.8, \"usl\": 10.2, \"decimals\": 2 }]. Copy the shape from an export", "type": "array", "items": {} } }, "required": [ "title", "type" ], "additionalProperties": false } } }, "required": [ "name" ], "additionalProperties": false } }, "routings": { "description": "Step sequences that work orders follow", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "product": { "description": "SKU of the product it makes (set when created)", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "steps": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "taskType": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The operation's task type" }, "blocksNext": { "description": "A gate: later steps wait for this one when the work order is released", "type": "boolean" } }, "required": [ "name", "taskType" ], "additionalProperties": false }, "description": "The released version's steps, in order. A change cuts a new version and releases it; released work orders keep theirs" } }, "required": [ "name", "steps" ], "additionalProperties": false } }, "machineData": { "description": "Per machine: signals, meters, condition rules and spare parts", "type": "array", "items": { "type": "object", "properties": { "ssu": { "type": "string", "minLength": 1, "description": "The machine's path: \"Site / Parent / Name\"" }, "signals": { "description": "Signals the machine reports: declared ahead of time, or annotated once they arrive. Never removed", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The signal's key as the machine connector reports it" }, "kind": { "type": "string", "enum": [ "state", "counter", "gauge" ], "description": "state (running / stopped / …), counter or gauge" }, "name": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "uom": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "isMeter": { "description": "A counter that accumulates into a meter (usage-based PM)", "type": "boolean" }, "isRunState": { "description": "The state signal downtime detection reads (one per machine)", "type": "boolean" }, "runningValue": { "description": "The run-state value that means running", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "key", "kind" ], "additionalProperties": false } }, "meters": { "description": "Manual meters (hours, cycles read by people). Signal-fed meters come from signals marked isMeter", "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 255 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "uom": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "key", "name" ], "additionalProperties": false } }, "conditionRules": { "description": "Condition-based maintenance: open a task when a value crosses a limit or a meter advances", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique on this machine" }, "mode": { "description": "threshold: a signal crosses a limit; meter_delta: every N units of a meter", "type": "string", "enum": [ "threshold", "meter_delta" ] }, "signal": { "type": "string", "minLength": 1, "description": "Signal key (threshold) or meter key (meter_delta)" }, "operator": { "description": "threshold mode: above (gt) or below (lt)", "type": "string", "enum": [ "gt", "lt" ] }, "threshold": { "type": "number", "description": "The limit, or the interval in meter units" }, "taskType": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The task type of the task it opens" }, "cooldownHours": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "enabled": { "type": "boolean" } }, "required": [ "name", "signal", "threshold", "taskType" ], "additionalProperties": false } }, "spareParts": { "description": "The machine's spare parts, by product SKU", "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string", "minLength": 1, "maxLength": 255 }, "quantity": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "sku", "quantity" ], "additionalProperties": false } } }, "required": [ "ssu" ], "additionalProperties": false } }, "flows": { "description": "Automations: a task's status change creates the next task", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "startsWith": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The task type that starts the flow (set when the flow is created; one flow per type)" }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "taskType": { "type": "string", "minLength": 1, "maxLength": 255 }, "x": { "description": "Position on the canvas", "type": "number" }, "y": { "type": "number" }, "inheritAssignee": { "description": "Tasks it creates take the triggering task's assignees", "type": "boolean" } }, "required": [ "taskType" ], "additionalProperties": false }, "description": "The task types on the canvas" }, "edges": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Task type whose status change triggers" }, "to": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Task type of the task created" }, "onStatus": { "type": "string", "enum": [ "open", "preparation", "ready", "dispatched", "submitted", "incomplete", "done", "declined" ], "description": "The status that triggers it" } }, "required": [ "from", "to", "onStatus" ], "additionalProperties": false }, "description": "When a task of `from` reaches `onStatus`, a task of `to` is created" } }, "required": [ "name", "startsWith", "nodes", "edges" ], "additionalProperties": false } }, "issues": { "description": "Issue reports people can file (from the app or a QR code)", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company: what people pick when they report" }, "taskType": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The task type of the task a report opens" }, "priority": { "description": "Priority name, or its level", "anyOf": [ { "type": "string" }, { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } ] }, "form": { "description": "The report form, in order. Replaces the whole form", "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The question; also how gates name the field" }, "type": { "type": "string", "enum": [ "text", "short_text", "number", "checkbox", "select", "datetime", "camera", "signature", "location", "qr", "segment", "products", "storage", "bin", "ssus", "ssu_status", "tag_chooser", "tags", "list", "target_time" ] }, "required": { "type": "boolean" }, "options": { "description": "Type-specific settings, as the Mobile Builder stores them: select → [{ \"id\": \"1\", \"title\": \"Pass\", \"type\": \"select\" }, …]; number → [{ \"id\": \"config\", \"uom\": \"mm\", \"target\": 10, \"lsl\": 9.8, \"usl\": 10.2, \"decimals\": 2 }]. Copy the shape from an export", "type": "array", "items": {} } }, "required": [ "title", "type" ], "additionalProperties": false } } }, "required": [ "name", "taskType" ], "additionalProperties": false } }, "permissionGroups": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "color": { "type": "string", "maxLength": 32 }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "tasks:view_all", "tasks:view_my_teams", "tasks:view_pre_active", "tasks:create", "tasks:delete", "tasks:reassign", "tasks:change_status_mobile", "task_types:view", "task_types:manage", "mobile_builder:view", "mobile_builder:manage", "flows:view", "flows:manage", "clients:view", "clients:manage", "geographic:view", "geographic:manage", "personnel:view", "personnel:manage", "subcontractors:view", "subcontractors:manage", "users:view", "users:manage", "access_requests:approve", "permissions:view", "permissions:manage", "settings:view", "settings:manage", "api_keys:view", "api_keys:manage", "webhooks:manage", "audit_logs:view", "data:export", "data:import", "products:view", "products:manage", "inventory:view", "inventory:manage", "inventory:adjust", "inventory:receive", "production:view", "production:manage", "work_orders:release", "machine_data:view", "machine_data:manage", "maintenance:view", "maintenance:manage", "quality:view", "quality:manage", "ncr:disposition", "documents:view", "documents:manage", "documents:publish", "insights:view", "handoffs:send", "partner_data:request", "partner_data:release", "ai_guidance:manage" ] }, "description": "Every permission the group grants (area:verb). The full set: listing replaces it" } }, "required": [ "name", "permissions" ], "additionalProperties": false } }, "roles": { "description": "What people are; each role grants one permission group", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company: what someone is (Technician, Dispatcher, Admin, …)" }, "permissionGroup": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The one permission group the role grants" }, "color": { "type": "string", "maxLength": 32 }, "isOperator": { "type": "boolean" }, "isWarehouse": { "type": "boolean" }, "isDefault": { "type": "boolean" } }, "required": [ "name", "permissionGroup" ], "additionalProperties": false } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company (case-insensitive)" }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" } }, "required": [ "name" ], "additionalProperties": false } }, "skills": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique in the company" }, "description": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] } }, "required": [ "name" ], "additionalProperties": false } }, "people": { "description": "Users already in the company, by email: their roles, teams, skills. Specs never invite", "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "A user already in the company: specs never invite anyone" }, "roles": { "description": "All of the person's roles (at least one): their permissions are the union", "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "teams": { "description": "All of the person's teams", "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "skills": { "description": "The person's skill certifications", "type": "array", "items": { "type": "object", "properties": { "skill": { "type": "string", "minLength": 1, "maxLength": 255 }, "certifiedAt": { "description": "ISO date", "type": "string" }, "expiresAt": { "description": "ISO date; null = doesn't expire", "type": [ "string", "null" ] } }, "required": [ "skill" ], "additionalProperties": false } }, "rank": { "type": "integer", "minimum": 0, "maximum": 5 }, "color": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ] }, "isActive": { "type": "boolean" } }, "required": [ "email" ], "additionalProperties": false } }, "subcontractors": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$", "description": "Unique in the company" }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "companyName": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "roles": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "rank": { "type": "integer", "minimum": 0, "maximum": 5 }, "color": { "anyOf": [ { "type": "string", "maxLength": 32 }, { "type": "null" } ] }, "isActive": { "type": "boolean" }, "expirationDate": { "description": "ISO date their engagement ends", "type": [ "string", "null" ] }, "address": { "description": "Full address. Used when created; not changed afterwards", "type": "string", "maxLength": 500 } }, "required": [ "email", "name" ], "additionalProperties": false } }, "inspectionPlans": { "description": "Which receipts or products must be inspected, and how", "type": "array", "items": { "type": "object", "properties": { "appliesTo": { "type": "string", "maxLength": 255, "description": "When it applies: receiving (incoming goods) or in_process" }, "product": { "description": "SKU of the product it covers", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "vendor": { "description": "Vendor it covers", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "taskType": { "description": "The inspection task type", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "samplingRule": { "description": "How many to inspect, e.g. { \"mode\": \"sample\", \"sampleSize\": 5 } or { \"mode\": \"all\" }", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "enabled": { "type": "boolean" } }, "required": [ "appliesTo" ], "additionalProperties": false } }, "guidance": { "description": "What the company tells every AI agent: company-wide and on specific machines, work centers, products, task types", "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string", "enum": [ "company", "ssu", "work_center", "product", "task_type" ] }, "ref": { "description": "Which one (not for company): an SSU path (\"Site / Line / Machine\"), a work center name, a product SKU, a task type name", "type": "string" }, "body": { "type": "string", "minLength": 1, "description": "What every agent should know (company: up to 4000 characters; one subject: 1000)" }, "thresholds": { "description": "stopMinutes: a stop longer than this matters; scrapPercent: scrap above this matters", "type": "object", "properties": { "stopMinutes": { "type": "number", "exclusiveMinimum": 0 }, "scrapPercent": { "type": "number", "minimum": 0, "maximum": 100 } }, "additionalProperties": false } }, "required": [ "subject", "body" ], "additionalProperties": false } } }, "required": [ "version" ], "additionalProperties": false, "description": "The factory spec (export one with config.export to see the shape)" } }, "required": [ "spec" ], "$defs": { "__schema0": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Unique among its siblings: the SSU's path (site / parent / … / name) is its key" }, "status": { "description": "SSU status name (from ssuStatuses, or one the company has)", "type": "string", "minLength": 1, "maxLength": 255 }, "workCenter": { "description": "Work center name", "type": "string", "minLength": 1, "maxLength": 255 }, "criticality": { "description": "1 (low) to 5 (critical)", "type": "integer", "minimum": 1, "maximum": 5 }, "assetClass": { "description": "Free-form grouping, e.g. CNC, press, gauge", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "make": { "description": "Machine make, from the global machine catalog (factories only); existing spellings are reused", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "model": { "description": "Machine model of that make (needs a make)", "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "sku": { "description": "Model-level SKU / part number (not a serial number)", "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "icon": { "type": "string", "enum": [ "cpu", "settings-2", "factory", "flame", "bot", "wrench", "fan", "package", "gauge" ] }, "isActive": { "type": "boolean" }, "isDefault": { "description": "The site's default SSU", "type": "boolean" }, "children": { "description": "Components (sub-assemblies) of this SSU", "type": "array", "items": { "$ref": "#/$defs/__schema0" } } }, "required": [ "name" ], "additionalProperties": false } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "problems": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "valid", "problems" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "config.validate", "x-eightyone-permission": "member", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/customers": { "get": { "operationId": "customers.list", "summary": "List customers", "description": "A factory's customers, who shipments go to: name, reference and ship-to address.\n\nPermission: `inventory:view`.", "tags": [ "Inventory" ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "externalRef": { "type": [ "string", "null" ] }, "shipToAddress": { "type": [ "string", "null" ] }, "isEightyOneCompany": { "type": "boolean", "description": "Shipments arrive in their EightyOne stock" } }, "required": [ "id", "name", "externalRef", "shipToAddress", "isEightyOneCompany" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "customers.list", "x-eightyone-permission": "inventory:view", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/data-packages": { "get": { "operationId": "data_packages.list", "summary": "List data packages", "description": "Traceability data packages you released to, or received from, partners.\n\nPermission: `handoffs:send`.", "tags": [ "Partner network" ], "parameters": [ { "name": "role", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "released", "received" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "from": {}, "object": {} }, "required": [ "id", "role", "createdAt", "from", "object" ], "additionalProperties": false } } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "data_packages.list", "x-eightyone-permission": "handoffs:send", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/data-packages/{id}": { "get": { "operationId": "data_packages.get", "summary": "Get a data package", "description": "A data package's content, with short-lived links to its photos.\n\nPermission: `handoffs:send`.", "tags": [ "Partner network" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "role": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "content": {}, "files": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" }, "url": { "type": "string" } }, "required": [ "index", "name", "url" ], "additionalProperties": false } } }, "required": [ "id", "role", "createdAt", "content", "files" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "data_packages.get", "x-eightyone-permission": "handoffs:send", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/downtime-events": { "get": { "operationId": "downtime_events.list", "summary": "List machine stoppages", "description": "Individual downtime events (newest first, up to 500): when each machine stopped, for how long, and the reason code someone classified it with. Use it to explain the totals from analytics.downtime. Filter by machine and window; `unclassifiedOnly` lists stops still waiting for a reason.\n\nPermission: `member`.", "tags": [ "Machines" ], "parameters": [ { "name": "ssuId", "in": "query", "required": false, "description": "SSU external id", "schema": { "description": "SSU external id", "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Stops that started at or after this time", "schema": { "description": "Stops that started at or after this time", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] } }, { "name": "to", "in": "query", "required": false, "description": "Stops that started before this time", "schema": { "description": "Stops that started before this time", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] } }, { "name": "unclassifiedOnly", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } }, { "name": "openOnly", "in": "query", "required": false, "description": "Only machines still stopped", "schema": { "description": "Only machines still stopped", "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ssuId": { "type": "string", "description": "SSU external id" }, "ssuName": { "type": [ "string", "null" ] }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "null while the machine is still stopped" }, "durationSeconds": { "type": [ "number", "null" ] }, "source": { "type": "string", "enum": [ "auto", "manual" ], "description": "auto: detected from machine telemetry; manual: reported by a person" }, "reason": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": [ "string", "null" ] }, "label": { "type": "string" } }, "required": [ "id", "code", "label" ], "additionalProperties": false }, { "type": "null" } ], "description": "The downtime reason code, once someone classified the stop" }, "note": { "type": [ "string", "null" ] } }, "required": [ "id", "ssuId", "ssuName", "startedAt", "endedAt", "durationSeconds", "source", "reason", "note" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "downtime_events.list", "x-eightyone-permission": "member", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" }, "post": { "operationId": "downtime_events.open", "summary": "Report a machine stopped", "description": "Record that a machine stopped now, for machines without telemetry (those report stops themselves). Close it with downtime_events_close when it runs again, and classify it with a reason. Needs 'Manage machine data'.\n\nPermission: `machine_data:manage`.", "tags": [ "Machines" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ssuId": { "type": "string", "description": "SSU external id" }, "note": { "type": "string", "maxLength": 1000 } }, "required": [ "ssuId" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ssuId": { "type": "string", "description": "SSU external id" }, "ssuName": { "type": [ "string", "null" ] }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "null while the machine is still stopped" }, "durationSeconds": { "type": [ "number", "null" ] }, "source": { "type": "string", "enum": [ "auto", "manual" ], "description": "auto: detected from machine telemetry; manual: reported by a person" }, "reason": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": [ "string", "null" ] }, "label": { "type": "string" } }, "required": [ "id", "code", "label" ], "additionalProperties": false }, { "type": "null" } ], "description": "The downtime reason code, once someone classified the stop" }, "note": { "type": [ "string", "null" ] } }, "required": [ "id", "ssuId", "ssuName", "startedAt", "endedAt", "durationSeconds", "source", "reason", "note" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "downtime_events.open", "x-eightyone-permission": "machine_data:manage", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "preview" } }, "/api/v1/downtime-events/{id}/classify": { "post": { "operationId": "downtime_events.classify", "summary": "Give a stop its reason", "description": "Classify a machine stoppage with a downtime reason code (reason_codes_list, kind downtime), optionally with a note. Re-classifying replaces the reason. Find stops waiting for one with downtime_events_list and unclassifiedOnly.\n\nPermission: `member`.", "tags": [ "Machines" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Downtime event id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reasonCodeId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "A downtime reason code id" }, "note": { "type": "string", "maxLength": 1000 } }, "required": [ "reasonCodeId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ssuId": { "type": "string", "description": "SSU external id" }, "ssuName": { "type": [ "string", "null" ] }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "null while the machine is still stopped" }, "durationSeconds": { "type": [ "number", "null" ] }, "source": { "type": "string", "enum": [ "auto", "manual" ], "description": "auto: detected from machine telemetry; manual: reported by a person" }, "reason": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": [ "string", "null" ] }, "label": { "type": "string" } }, "required": [ "id", "code", "label" ], "additionalProperties": false }, { "type": "null" } ], "description": "The downtime reason code, once someone classified the stop" }, "note": { "type": [ "string", "null" ] } }, "required": [ "id", "ssuId", "ssuName", "startedAt", "endedAt", "durationSeconds", "source", "reason", "note" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "downtime_events.classify", "x-eightyone-permission": "member", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "transactional" } }, "/api/v1/downtime-events/{id}/close": { "post": { "operationId": "downtime_events.close", "summary": "Report a machine running again", "description": "End a stoppage now. Closing one that already ended changes nothing. Needs 'Manage machine data'.\n\nPermission: `machine_data:manage`.", "tags": [ "Machines" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Downtime event id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ssuId": { "type": "string", "description": "SSU external id" }, "ssuName": { "type": [ "string", "null" ] }, "startedAt": { "type": "string", "format": "date-time" }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "null while the machine is still stopped" }, "durationSeconds": { "type": [ "number", "null" ] }, "source": { "type": "string", "enum": [ "auto", "manual" ], "description": "auto: detected from machine telemetry; manual: reported by a person" }, "reason": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": [ "string", "null" ] }, "label": { "type": "string" } }, "required": [ "id", "code", "label" ], "additionalProperties": false }, { "type": "null" } ], "description": "The downtime reason code, once someone classified the stop" }, "note": { "type": [ "string", "null" ] } }, "required": [ "id", "ssuId", "ssuName", "startedAt", "endedAt", "durationSeconds", "source", "reason", "note" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "downtime_events.close", "x-eightyone-permission": "machine_data:manage", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "preview" } }, "/api/v1/downtime-events/summary": { "get": { "operationId": "downtime_events.summary", "summary": "Downtime by machine and reason", "description": "Recorded stoppages per machine in a window (default: the last 30 days), most stopped time first, each broken down by reason code: the direct answer to \"which machines were down most, and why?\". Counts only the part of each stop inside the window; a stop still open counts up to the window end. Complements analytics.downtime, which measures time in a DOWN / MAINTENANCE status.\n\nPermission: `member`.", "tags": [ "Machines" ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Window start (ISO 8601). Default: 30 days before `to`", "schema": { "description": "Window start (ISO 8601). Default: 30 days before `to`", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] } }, { "name": "to", "in": "query", "required": false, "description": "Window end, exclusive (ISO 8601). Default: now", "schema": { "description": "Window end, exclusive (ISO 8601). Default: now", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "type": "object", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" } }, "required": [ "from", "to" ], "additionalProperties": false }, "data": { "type": "array", "items": { "type": "object", "properties": { "ssuId": { "type": "string", "description": "SSU external id" }, "ssuName": { "type": [ "string", "null" ] }, "seconds": { "type": "number" }, "hours": { "type": "number" }, "stops": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "openStops": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Stops not yet ended" }, "byReason": { "type": "array", "items": { "type": "object", "properties": { "reasonCodeId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "code": { "type": [ "string", "null" ] }, "label": { "type": "string", "description": "'Unclassified' when no one gave a reason yet" }, "seconds": { "type": "number" }, "stops": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "reasonCodeId", "code", "label", "seconds", "stops" ], "additionalProperties": false } } }, "required": [ "ssuId", "ssuName", "seconds", "hours", "stops", "openStops", "byReason" ], "additionalProperties": false } } }, "required": [ "range", "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "downtime_events.summary", "x-eightyone-permission": "member", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/guidance": { "get": { "operationId": "guidance.list", "summary": "List company guidance for agents", "description": "What the company's administrators tell every AI agent: company-wide guidance and notes on specific machines, work centers, products and task types, with any thresholds they set.\n\nPermission: `member`.", "tags": [ "Guides" ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string", "enum": [ "company", "ssu", "work_center", "product", "task_type" ] }, "ref": { "description": "The SSU / product / task type external id, or the work center name", "type": [ "string", "null" ] }, "name": { "description": "What it's about, by name", "type": [ "string", "null" ] }, "body": { "type": "string" }, "thresholds": { "type": "object", "properties": { "stopMinutes": { "description": "A machine stop longer than this (minutes) matters", "type": "number", "exclusiveMinimum": 0 }, "scrapPercent": { "description": "A scrap rate above this (percent) matters", "type": "number", "minimum": 0, "maximum": 100 } }, "additionalProperties": false }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "reviewedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "subject", "ref", "name", "body", "thresholds", "version", "reviewedAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "guidance.list", "x-eightyone-permission": "member", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" }, "put": { "operationId": "guidance.set", "summary": "Set company guidance for agents", "description": "Write the guidance agents get for the company, or for one machine, work center, product or task type. Replaces that subject's text; the previous version is kept in the audit log. Every agent connected to the company follows it.\n\nPermission: `ai_guidance:manage`.", "tags": [ "Guides" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "enum": [ "company", "ssu", "work_center", "product", "task_type" ] }, "ref": { "description": "Which one (not for company): SSU external id, work center name, product external id or SKU, task type external id", "type": "string" }, "body": { "type": "string", "minLength": 1, "description": "Plain text or Markdown. Company: up to 4000 characters; one subject: 1000" }, "thresholds": { "type": "object", "properties": { "stopMinutes": { "description": "A machine stop longer than this (minutes) matters", "type": "number", "exclusiveMinimum": 0 }, "scrapPercent": { "description": "A scrap rate above this (percent) matters", "type": "number", "minimum": 0, "maximum": 100 } }, "additionalProperties": false }, "reviewed": { "description": "Mark it as reviewed now (agents see how fresh it is)", "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } }, "required": [ "subject", "body" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "enum": [ "company", "ssu", "work_center", "product", "task_type" ] }, "ref": { "description": "The SSU / product / task type external id, or the work center name", "type": [ "string", "null" ] }, "name": { "description": "What it's about, by name", "type": [ "string", "null" ] }, "body": { "type": "string" }, "thresholds": { "type": "object", "properties": { "stopMinutes": { "description": "A machine stop longer than this (minutes) matters", "type": "number", "exclusiveMinimum": 0 }, "scrapPercent": { "description": "A scrap rate above this (percent) matters", "type": "number", "minimum": 0, "maximum": 100 } }, "additionalProperties": false }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "reviewedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "subject", "ref", "name", "body", "thresholds", "version", "reviewedAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "guidance.set", "x-eightyone-permission": "ai_guidance:manage", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "transactional" }, "delete": { "operationId": "guidance.delete", "summary": "Remove company guidance for agents", "description": "Remove the guidance for the company or one subject. The audit log keeps what it said.\n\nPermission: `ai_guidance:manage`.", "tags": [ "Guides" ], "parameters": [ { "name": "subject", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "company", "ssu", "work_center", "product", "task_type" ] } }, { "name": "ref", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "responses": { "204": { "description": "Success", "content": { "application/json": { "schema": { "type": "null" } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "guidance.delete", "x-eightyone-permission": "ai_guidance:manage", "x-eightyone-effect": "destructive", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "transactional" } }, "/api/v1/guides": { "get": { "operationId": "guide.get", "summary": "Read a guide", "description": "EightyOne concepts and how to read the data: the glossary, downtime, maintenance, production, inventory, quality, commissioning, what deserves attention, and this company's own guidance (topic \"company\"). Without a topic, lists the topics. Read the glossary before working on an unfamiliar area.\n\nPermission: `member`.", "tags": [ "Guides" ], "parameters": [ { "name": "topic", "in": "query", "required": false, "description": "\"company\": what this company's administrators tell agents, including notes on specific machines", "schema": { "description": "\"company\": what this company's administrators tell agents, including notes on specific machines", "type": "string", "enum": [ "glossary", "downtime", "maintenance", "production", "inventory", "quality", "commissioning", "signals", "company" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "topic": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "body": { "type": "string", "description": "Markdown" }, "topics": { "type": "array", "items": { "type": "object", "properties": { "topic": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" } }, "required": [ "topic", "title", "summary" ], "additionalProperties": false } } }, "required": [ "topic", "title", "body", "topics" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "guide.get", "x-eightyone-permission": "member", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/handoffs": { "post": { "operationId": "handoffs.send", "summary": "Send a task to a partner company", "description": "Hand one of your tasks to another EightyOne company (by its short name, or a partner subcontractor). The partner gets its own copy; your people come off the task. Goods can travel with it (items), and a data-request task carries the scopes it asks for.\n\nPermission: `handoffs:send`.", "tags": [ "Partner network" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "taskId": { "type": "string", "description": "Your task's id" }, "recipientShortName": { "type": "string" }, "subContractorId": { "description": "A subcontractor that is an EightyOne company", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "items": { "default": [], "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string", "description": "Your product's id (its external id)" }, "quantity": { "type": "number", "exclusiveMinimum": 0 }, "fromStorageUnitId": { "type": "string", "description": "Your storage unit's id the goods leave from" }, "lotCode": { "description": "Lot-tracked products: the lot to send", "type": "string" }, "lineItemIds": { "description": "Serialized units: their line item ids; the count is the quantity", "type": "array", "items": { "type": "string" } }, "mode": { "default": "transfer", "description": "custody: the goods stay yours, held by the partner", "type": "string", "enum": [ "transfer", "custody" ] } }, "required": [ "productId", "quantity", "fromStorageUnitId" ], "additionalProperties": false } }, "dataRequest": { "type": "object", "properties": { "scopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "scopes" ] } }, "required": [ "taskId" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "direction": { "type": "string", "enum": [ "incoming", "outgoing" ] }, "state": { "type": "string" }, "partner": { "type": "object", "properties": { "shortName": { "type": "string" }, "name": { "type": "string" } }, "required": [ "shortName", "name" ], "additionalProperties": false }, "taskId": { "type": "string", "description": "This company's own task (never the partner's)" }, "status": { "type": "string" }, "declinedReason": { "type": [ "string", "null" ] }, "requestedItems": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": {} } }, "dataRequest": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "state": { "type": "string" }, "releasedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "scopes", "state", "releasedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "direction": { "type": "string", "enum": [ "incoming", "outgoing" ] }, "state": { "type": "string" }, "partner": { "type": "object", "properties": { "shortName": { "type": "string" }, "name": { "type": "string" } }, "required": [ "shortName", "name" ], "additionalProperties": false }, "taskId": { "type": [ "string", "null" ] }, "handoffId": { "type": [ "string", "null" ] }, "shipmentCode": { "type": [ "string", "null" ] }, "returnOf": { "type": [ "string", "null" ] }, "receivingStorageUnit": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "linkActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" }, "quantity": { "type": "number" }, "mode": { "type": "string" } }, "required": [ "id", "name", "quantity", "mode" ], "additionalProperties": {} } } }, "required": [ "id", "kind", "direction", "state", "partner", "taskId", "handoffId", "shipmentCode", "returnOf", "receivingStorageUnit", "linkActive", "createdAt", "lines" ], "additionalProperties": false } }, "linkActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "direction", "state", "partner", "taskId", "status", "declinedReason", "requestedItems", "dataRequest", "deliveries", "linkActive", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "handoffs.send", "x-eightyone-permission": "handoffs:send", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "transactional" }, "get": { "operationId": "handoffs.list", "summary": "List handoffs", "description": "Tasks you sent to, or received from, partner companies (newest first, up to 500).\n\nPermission: `handoffs:send`.", "tags": [ "Partner network" ], "parameters": [ { "name": "direction", "in": "query", "required": false, "schema": { "default": "all", "type": "string", "enum": [ "incoming", "outgoing", "all" ] } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "withdrawn", "deleted" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "direction": { "type": "string", "enum": [ "incoming", "outgoing" ] }, "state": { "type": "string" }, "partner": { "type": "object", "properties": { "shortName": { "type": "string" }, "name": { "type": "string" } }, "required": [ "shortName", "name" ], "additionalProperties": false }, "taskId": { "type": "string", "description": "This company's own task (never the partner's)" }, "status": { "type": "string" }, "declinedReason": { "type": [ "string", "null" ] }, "requestedItems": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": {} } }, "dataRequest": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "state": { "type": "string" }, "releasedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "scopes", "state", "releasedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "direction": { "type": "string", "enum": [ "incoming", "outgoing" ] }, "state": { "type": "string" }, "partner": { "type": "object", "properties": { "shortName": { "type": "string" }, "name": { "type": "string" } }, "required": [ "shortName", "name" ], "additionalProperties": false }, "taskId": { "type": [ "string", "null" ] }, "handoffId": { "type": [ "string", "null" ] }, "shipmentCode": { "type": [ "string", "null" ] }, "returnOf": { "type": [ "string", "null" ] }, "receivingStorageUnit": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "linkActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" }, "quantity": { "type": "number" }, "mode": { "type": "string" } }, "required": [ "id", "name", "quantity", "mode" ], "additionalProperties": {} } } }, "required": [ "id", "kind", "direction", "state", "partner", "taskId", "handoffId", "shipmentCode", "returnOf", "receivingStorageUnit", "linkActive", "createdAt", "lines" ], "additionalProperties": false } }, "linkActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "direction", "state", "partner", "taskId", "status", "declinedReason", "requestedItems", "dataRequest", "deliveries", "linkActive", "createdAt" ], "additionalProperties": false } } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "handoffs.list", "x-eightyone-permission": "handoffs:send", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/handoffs/{id}": { "get": { "operationId": "handoffs.get", "summary": "Get a handoff", "description": "One handoff from your side.\n\nPermission: `handoffs:send`.", "tags": [ "Partner network" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "direction": { "type": "string", "enum": [ "incoming", "outgoing" ] }, "state": { "type": "string" }, "partner": { "type": "object", "properties": { "shortName": { "type": "string" }, "name": { "type": "string" } }, "required": [ "shortName", "name" ], "additionalProperties": false }, "taskId": { "type": "string", "description": "This company's own task (never the partner's)" }, "status": { "type": "string" }, "declinedReason": { "type": [ "string", "null" ] }, "requestedItems": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": {} } }, "dataRequest": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "state": { "type": "string" }, "releasedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "scopes", "state", "releasedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "direction": { "type": "string", "enum": [ "incoming", "outgoing" ] }, "state": { "type": "string" }, "partner": { "type": "object", "properties": { "shortName": { "type": "string" }, "name": { "type": "string" } }, "required": [ "shortName", "name" ], "additionalProperties": false }, "taskId": { "type": [ "string", "null" ] }, "handoffId": { "type": [ "string", "null" ] }, "shipmentCode": { "type": [ "string", "null" ] }, "returnOf": { "type": [ "string", "null" ] }, "receivingStorageUnit": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "linkActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" }, "quantity": { "type": "number" }, "mode": { "type": "string" } }, "required": [ "id", "name", "quantity", "mode" ], "additionalProperties": {} } } }, "required": [ "id", "kind", "direction", "state", "partner", "taskId", "handoffId", "shipmentCode", "returnOf", "receivingStorageUnit", "linkActive", "createdAt", "lines" ], "additionalProperties": false } }, "linkActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "direction", "state", "partner", "taskId", "status", "declinedReason", "requestedItems", "dataRequest", "deliveries", "linkActive", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "handoffs.get", "x-eightyone-permission": "handoffs:send", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" }, "delete": { "operationId": "handoffs.withdraw", "summary": "Withdraw a sent handoff", "description": "Take back an active handoff you sent; the partner's copy is removed.\n\nPermission: `handoffs:send`.", "tags": [ "Partner network" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "204": { "description": "Success", "content": { "application/json": { "schema": { "type": "null" } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "handoffs.withdraw", "x-eightyone-permission": "handoffs:send", "x-eightyone-effect": "destructive", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "unsupported" } }, "/api/v1/handoffs/{id}/decline": { "post": { "operationId": "handoffs.decline", "summary": "Decline a received handoff", "description": "Decline a task a partner sent you, with a reason they will see.\n\nPermission: `handoffs:send`.", "tags": [ "Partner network" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1 } }, "required": [ "reason" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "direction": { "type": "string", "enum": [ "incoming", "outgoing" ] }, "state": { "type": "string" }, "partner": { "type": "object", "properties": { "shortName": { "type": "string" }, "name": { "type": "string" } }, "required": [ "shortName", "name" ], "additionalProperties": false }, "taskId": { "type": "string", "description": "This company's own task (never the partner's)" }, "status": { "type": "string" }, "declinedReason": { "type": [ "string", "null" ] }, "requestedItems": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": {} } }, "dataRequest": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "state": { "type": "string" }, "releasedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "scopes", "state", "releasedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "deliveries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "direction": { "type": "string", "enum": [ "incoming", "outgoing" ] }, "state": { "type": "string" }, "partner": { "type": "object", "properties": { "shortName": { "type": "string" }, "name": { "type": "string" } }, "required": [ "shortName", "name" ], "additionalProperties": false }, "taskId": { "type": [ "string", "null" ] }, "handoffId": { "type": [ "string", "null" ] }, "shipmentCode": { "type": [ "string", "null" ] }, "returnOf": { "type": [ "string", "null" ] }, "receivingStorageUnit": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "linkActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" }, "quantity": { "type": "number" }, "mode": { "type": "string" } }, "required": [ "id", "name", "quantity", "mode" ], "additionalProperties": {} } } }, "required": [ "id", "kind", "direction", "state", "partner", "taskId", "handoffId", "shipmentCode", "returnOf", "receivingStorageUnit", "linkActive", "createdAt", "lines" ], "additionalProperties": false } }, "linkActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "direction", "state", "partner", "taskId", "status", "declinedReason", "requestedItems", "dataRequest", "deliveries", "linkActive", "createdAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "handoffs.decline", "x-eightyone-permission": "handoffs:send", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "transactional" } }, "/api/v1/handoffs/{id}/timeline": { "get": { "operationId": "handoffs.timeline", "summary": "Handoff timeline", "description": "What happened on a handoff, in order; your own people are named, the partner's are not.\n\nPermission: `handoffs:send`.", "tags": [ "Partner network" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "by": { "type": "string", "enum": [ "you", "partner" ] }, "actorName": { "description": "Only your own people are named", "type": [ "string", "null" ] }, "payload": {} }, "required": [ "type", "at", "by", "actorName", "payload" ], "additionalProperties": false } } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "handoffs.timeline", "x-eightyone-permission": "handoffs:send", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/inventory-counts": { "get": { "operationId": "inventory_counts.list", "summary": "List cycle counts", "description": "Cycle counts, newest first: which storage unit, status (draft, in_progress, completed = finalized and waiting to be reconciled, reconciled) and totals. inventory_counts_get shows the lines and discrepancies.\n\nPermission: `inventory:view`.", "tags": [ "Inventory" ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "in_progress", "completed", "reconciled" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "storageUnit": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "site": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "site" ], "additionalProperties": false }, { "type": "null" } ] }, "status": { "type": "string", "description": "draft / in_progress / completed (finalized, awaiting reconciliation) / reconciled" }, "countType": { "type": [ "string", "null" ] }, "totalExpected": { "type": [ "number", "null" ] }, "totalCounted": { "type": [ "number", "null" ] }, "taskId": { "description": "The count task operators fill in, if any", "type": [ "string", "null" ] }, "dueDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "reconciledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "storageUnit", "status", "countType", "totalExpected", "totalCounted", "taskId", "dueDate", "completedAt", "reconciledAt", "createdAt" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "inventory_counts.list", "x-eightyone-permission": "inventory:view", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" }, "post": { "operationId": "inventory_counts.create", "summary": "Start a cycle count", "description": "Open a count of one storage unit. It snapshots what the system expects there, and when the company has an inventory task type it also creates the count task operators fill in from the app. Needs 'Manage inventory'.\n\nPermission: `inventory:manage`.", "tags": [ "Inventory" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "storageUnitId": { "type": "string", "description": "Storage unit external id (storage_units_list)" }, "title": { "description": "The count task's title", "type": "string" }, "dueDate": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] } }, "required": [ "storageUnitId" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "storageUnit": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "site": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "site" ], "additionalProperties": false }, { "type": "null" } ] }, "status": { "type": "string", "description": "draft / in_progress / completed (finalized, awaiting reconciliation) / reconciled" }, "countType": { "type": [ "string", "null" ] }, "totalExpected": { "type": [ "number", "null" ] }, "totalCounted": { "type": [ "number", "null" ] }, "taskId": { "description": "The count task operators fill in, if any", "type": [ "string", "null" ] }, "dueDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "reconciledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "lineId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sku": { "type": [ "string", "null" ] }, "product": { "type": [ "string", "null" ] }, "bin": { "type": [ "string", "null" ] }, "lotCode": { "type": [ "string", "null" ] }, "serialCode": { "type": [ "string", "null" ] }, "expected": { "type": "number", "description": "On hand by the system (refreshed when the count is finalized)" }, "counted": { "type": "number" }, "discrepancy": { "description": "counted − expected, once finalized", "type": [ "number", "null" ] }, "movedDuringCount": { "type": "boolean", "description": "Stock of this product moved in or out while the count was open" }, "decision": { "description": "accepted / adjusted / ignored, once reconciled", "type": [ "string", "null" ] } }, "required": [ "lineId", "sku", "product", "bin", "lotCode", "serialCode", "expected", "counted", "discrepancy", "movedDuringCount", "decision" ], "additionalProperties": false } } }, "required": [ "id", "storageUnit", "status", "countType", "totalExpected", "totalCounted", "taskId", "dueDate", "completedAt", "reconciledAt", "createdAt", "lines" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "inventory_counts.create", "x-eightyone-permission": "inventory:manage", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "transactional" } }, "/api/v1/inventory-counts/{id}": { "get": { "operationId": "inventory_counts.get", "summary": "Get a cycle count", "description": "A cycle count with its lines: expected (on hand by the system), counted, the discrepancy once finalized, and whether stock moved while it was open (a reason to recount rather than adjust).\n\nPermission: `inventory:view`.", "tags": [ "Inventory" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "storageUnit": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "site": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "site" ], "additionalProperties": false }, { "type": "null" } ] }, "status": { "type": "string", "description": "draft / in_progress / completed (finalized, awaiting reconciliation) / reconciled" }, "countType": { "type": [ "string", "null" ] }, "totalExpected": { "type": [ "number", "null" ] }, "totalCounted": { "type": [ "number", "null" ] }, "taskId": { "description": "The count task operators fill in, if any", "type": [ "string", "null" ] }, "dueDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "reconciledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "lineId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sku": { "type": [ "string", "null" ] }, "product": { "type": [ "string", "null" ] }, "bin": { "type": [ "string", "null" ] }, "lotCode": { "type": [ "string", "null" ] }, "serialCode": { "type": [ "string", "null" ] }, "expected": { "type": "number", "description": "On hand by the system (refreshed when the count is finalized)" }, "counted": { "type": "number" }, "discrepancy": { "description": "counted − expected, once finalized", "type": [ "number", "null" ] }, "movedDuringCount": { "type": "boolean", "description": "Stock of this product moved in or out while the count was open" }, "decision": { "description": "accepted / adjusted / ignored, once reconciled", "type": [ "string", "null" ] } }, "required": [ "lineId", "sku", "product", "bin", "lotCode", "serialCode", "expected", "counted", "discrepancy", "movedDuringCount", "decision" ], "additionalProperties": false } } }, "required": [ "id", "storageUnit", "status", "countType", "totalExpected", "totalCounted", "taskId", "dueDate", "completedAt", "reconciledAt", "createdAt", "lines" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "inventory_counts.get", "x-eightyone-permission": "inventory:view", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/inventory-counts/{id}/finalize": { "post": { "operationId": "inventory_counts.finalize", "summary": "Finish a cycle count", "description": "Close counting: each line's expected quantity becomes what's on hand now, discrepancies are computed, and anything on hand the count never saw becomes a line counted 0. Nothing is posted to stock until it's reconciled. Needs 'Manage inventory'.\n\nPermission: `inventory:manage`.", "tags": [ "Inventory" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "storageUnit": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "site": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "site" ], "additionalProperties": false }, { "type": "null" } ] }, "status": { "type": "string", "description": "draft / in_progress / completed (finalized, awaiting reconciliation) / reconciled" }, "countType": { "type": [ "string", "null" ] }, "totalExpected": { "type": [ "number", "null" ] }, "totalCounted": { "type": [ "number", "null" ] }, "taskId": { "description": "The count task operators fill in, if any", "type": [ "string", "null" ] }, "dueDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "reconciledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "lineId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sku": { "type": [ "string", "null" ] }, "product": { "type": [ "string", "null" ] }, "bin": { "type": [ "string", "null" ] }, "lotCode": { "type": [ "string", "null" ] }, "serialCode": { "type": [ "string", "null" ] }, "expected": { "type": "number", "description": "On hand by the system (refreshed when the count is finalized)" }, "counted": { "type": "number" }, "discrepancy": { "description": "counted − expected, once finalized", "type": [ "number", "null" ] }, "movedDuringCount": { "type": "boolean", "description": "Stock of this product moved in or out while the count was open" }, "decision": { "description": "accepted / adjusted / ignored, once reconciled", "type": [ "string", "null" ] } }, "required": [ "lineId", "sku", "product", "bin", "lotCode", "serialCode", "expected", "counted", "discrepancy", "movedDuringCount", "decision" ], "additionalProperties": false } } }, "required": [ "id", "storageUnit", "status", "countType", "totalExpected", "totalCounted", "taskId", "dueDate", "completedAt", "reconciledAt", "createdAt", "lines" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "inventory_counts.finalize", "x-eightyone-permission": "inventory:manage", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "transactional" } }, "/api/v1/inventory-counts/{id}/lines": { "post": { "operationId": "inventory_counts.record_lines", "summary": "Record counted quantities", "description": "Add what someone counted to an open count, by SKU (and bin, lot or serial where it matters). Quantities add to what was already counted for that line, as in the dashboard. Then finalize it. Needs 'Manage inventory'.\n\nPermission: `inventory:manage`.", "tags": [ "Inventory" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Count id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "quantity": { "type": "number", "minimum": 0 }, "bin": { "type": "string", "enum": [ "goods", "bads", "quarantine" ] }, "lotCode": { "type": "string" }, "serialCode": { "type": "string" } }, "required": [ "sku", "quantity" ], "additionalProperties": false } } }, "required": [ "lines" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "storageUnit": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "site": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "site" ], "additionalProperties": false }, { "type": "null" } ] }, "status": { "type": "string", "description": "draft / in_progress / completed (finalized, awaiting reconciliation) / reconciled" }, "countType": { "type": [ "string", "null" ] }, "totalExpected": { "type": [ "number", "null" ] }, "totalCounted": { "type": [ "number", "null" ] }, "taskId": { "description": "The count task operators fill in, if any", "type": [ "string", "null" ] }, "dueDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "reconciledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "lineId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sku": { "type": [ "string", "null" ] }, "product": { "type": [ "string", "null" ] }, "bin": { "type": [ "string", "null" ] }, "lotCode": { "type": [ "string", "null" ] }, "serialCode": { "type": [ "string", "null" ] }, "expected": { "type": "number", "description": "On hand by the system (refreshed when the count is finalized)" }, "counted": { "type": "number" }, "discrepancy": { "description": "counted − expected, once finalized", "type": [ "number", "null" ] }, "movedDuringCount": { "type": "boolean", "description": "Stock of this product moved in or out while the count was open" }, "decision": { "description": "accepted / adjusted / ignored, once reconciled", "type": [ "string", "null" ] } }, "required": [ "lineId", "sku", "product", "bin", "lotCode", "serialCode", "expected", "counted", "discrepancy", "movedDuringCount", "decision" ], "additionalProperties": false } } }, "required": [ "id", "storageUnit", "status", "countType", "totalExpected", "totalCounted", "taskId", "dueDate", "completedAt", "reconciledAt", "createdAt", "lines" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "inventory_counts.record_lines", "x-eightyone-permission": "inventory:manage", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "transactional" } }, "/api/v1/inventory-counts/{id}/reconcile": { "post": { "operationId": "inventory_counts.reconcile", "summary": "Post a cycle count to stock", "description": "Decide each line of a finalized count and post it. accepted: stock becomes the counted quantity; adjusted: becomes adjustedQuantity; ignored (and any line not listed): stock stays as the system has it. Every write-off needs an adjustment reasonCodeId (reason_codes_list kind adjustment). Needs 'Manage inventory' and 'Adjust inventory'. Preview it first: it lists each addition, write-off and bin move.\n\nPermission: `inventory:manage + inventory:adjust`.", "tags": [ "Inventory" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decisions": { "maxItems": 2000, "type": "array", "items": { "type": "object", "properties": { "lineId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "decision": { "type": "string", "enum": [ "accepted", "adjusted", "ignored" ] }, "adjustedQuantity": { "type": "number", "minimum": 0 }, "reasonCodeId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "notes": { "type": "string", "maxLength": 1000 } }, "required": [ "lineId", "decision" ], "additionalProperties": false } } }, "required": [ "decisions" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "storageUnit": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "site": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "site" ], "additionalProperties": false }, { "type": "null" } ] }, "status": { "type": "string", "description": "draft / in_progress / completed (finalized, awaiting reconciliation) / reconciled" }, "countType": { "type": [ "string", "null" ] }, "totalExpected": { "type": [ "number", "null" ] }, "totalCounted": { "type": [ "number", "null" ] }, "taskId": { "description": "The count task operators fill in, if any", "type": [ "string", "null" ] }, "dueDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "reconciledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "lineId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sku": { "type": [ "string", "null" ] }, "product": { "type": [ "string", "null" ] }, "bin": { "type": [ "string", "null" ] }, "lotCode": { "type": [ "string", "null" ] }, "serialCode": { "type": [ "string", "null" ] }, "expected": { "type": "number", "description": "On hand by the system (refreshed when the count is finalized)" }, "counted": { "type": "number" }, "discrepancy": { "description": "counted − expected, once finalized", "type": [ "number", "null" ] }, "movedDuringCount": { "type": "boolean", "description": "Stock of this product moved in or out while the count was open" }, "decision": { "description": "accepted / adjusted / ignored, once reconciled", "type": [ "string", "null" ] } }, "required": [ "lineId", "sku", "product", "bin", "lotCode", "serialCode", "expected", "counted", "discrepancy", "movedDuringCount", "decision" ], "additionalProperties": false } } }, "required": [ "id", "storageUnit", "status", "countType", "totalExpected", "totalCounted", "taskId", "dueDate", "completedAt", "reconciledAt", "createdAt", "lines" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "inventory_counts.reconcile", "x-eightyone-permission": "inventory:manage + inventory:adjust", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "preview" } }, "/api/v1/inventory/reorder-suggestions": { "get": { "operationId": "inventory.reorder_suggestions", "summary": "Reorder suggestions", "description": "Products below their minimum or at their dynamic reorder point (lead time × measured consumption), with the suggested quantity and vendor. Quantities and days only.\n\nPermission: `products:view`.", "tags": [ "Inventory" ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "productName": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "onHand": { "type": "number" }, "minQty": { "type": "number" }, "suggestedQty": { "type": "number" }, "suggestedVendorName": { "type": [ "string", "null" ] }, "vendorLeadTime": { "description": "Days", "type": [ "number", "null" ] }, "dailyConsumption": { "type": [ "number", "null" ] }, "reorderPoint": { "type": [ "number", "null" ] }, "triggerReason": { "type": "string", "enum": [ "below_min", "below_reorder_point" ] } }, "required": [ "productName", "sku", "onHand", "minQty", "suggestedQty", "suggestedVendorName", "vendorLeadTime", "dailyConsumption", "reorderPoint", "triggerReason" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "inventory.reorder_suggestions", "x-eightyone-permission": "products:view", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/inventory/stock-levels": { "get": { "operationId": "inventory.stock_levels", "summary": "Stock on hand", "description": "Goods on hand per product and storage site (up to 2000 rows), by the same rule reordering uses: good stock only (not the bads bin), not counting stock held by a partner. Filter by product id, SKU or storage site.\n\nPermission: `inventory:view`.", "tags": [ "Inventory" ], "parameters": [ { "name": "productId", "in": "query", "required": false, "description": "Product external id", "schema": { "description": "Product external id", "type": "string" } }, { "name": "sku", "in": "query", "required": false, "description": "Product SKU (case-insensitive)", "schema": { "description": "Product SKU (case-insensitive)", "type": "string" } }, { "name": "storageSiteId", "in": "query", "required": false, "description": "Storage site external id", "schema": { "description": "Storage site external id", "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "uom": { "type": [ "string", "null" ] }, "itemClass": { "type": "string", "description": "raw, wip, finished, operations or spare_part" }, "storageSiteId": { "type": [ "string", "null" ] }, "storageSiteName": { "type": [ "string", "null" ] }, "onHand": { "type": "number" } }, "required": [ "productId", "sku", "name", "uom", "itemClass", "storageSiteId", "storageSiteName", "onHand" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "inventory.stock_levels", "x-eightyone-permission": "inventory:view", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/line-items/ssu": { "get": { "operationId": "line_items.find_ssu_by_barcode", "summary": "Find the SSU holding a scanned unit", "description": "Resolve a scanned line-item barcode to the SSU (machine / location) whose storage unit holds it. 404 when the unit, its storage unit or that storage unit's SSU is unknown.\n\nPermission: `member`.", "tags": [ "Inventory" ], "parameters": [ { "name": "barcode", "in": "query", "required": true, "description": "Line item barcode (code)", "schema": { "type": "string", "minLength": 1, "description": "Line item barcode (code)" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "isActive": { "type": "boolean" }, "location": { "anyOf": [ {}, { "type": "null" } ], "description": "GeoJSON point (PostGIS geometry), or null" } }, "required": [ "id", "name", "imageUrl", "isActive", "location" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "line_items.find_ssu_by_barcode", "x-eightyone-permission": "member", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/machine-catalog/makes": { "get": { "operationId": "machine_catalog.search_makes", "summary": "Search machine makes", "description": "Search the global catalog of machine manufacturers (e.g. 'Trumpf'). Use the existing spelling when it matches: everyone shares one catalog.\n\nPermission: `member`.", "tags": [ "Machines" ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Part of the make's name; empty lists common makes", "schema": { "description": "Part of the make's name; empty lists common makes", "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" }, "matchType": { "anyOf": [ { "type": "string", "enum": [ "exact", "prefix", "contains", "similar" ] }, { "type": "null" } ], "description": "similar = a 'did you mean' suggestion for a likely misspelling" } }, "required": [ "id", "name", "matchType" ], "additionalProperties": false } } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "machine_catalog.search_makes", "x-eightyone-permission": "member", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/machine-catalog/models": { "get": { "operationId": "machine_catalog.search_models", "summary": "Search machine models", "description": "Search the models of one make in the global catalog.\n\nPermission: `member`.", "tags": [ "Machines" ], "parameters": [ { "name": "makeId", "in": "query", "required": true, "description": "Make id from machine_catalog.search_makes", "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Make id from machine_catalog.search_makes" } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" }, "matchType": { "anyOf": [ { "type": "string", "enum": [ "exact", "prefix", "contains", "similar" ] }, { "type": "null" } ], "description": "similar = a 'did you mean' suggestion for a likely misspelling" } }, "required": [ "id", "name", "matchType" ], "additionalProperties": false } } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "machine_catalog.search_models", "x-eightyone-permission": "member", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/machine-catalog/sku-lookup": { "get": { "operationId": "machine_catalog.lookup_sku", "summary": "Find a machine by SKU", "description": "The make and model registered for a model-level SKU / part number (not a serial number).\n\nPermission: `member`.", "tags": [ "Machines" ], "parameters": [ { "name": "sku", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "make": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "model": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false } }, "required": [ "make", "model" ], "additionalProperties": false } } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "machine_catalog.lookup_sku", "x-eightyone-permission": "member", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/me": { "get": { "operationId": "me.get", "summary": "Who am I", "description": "The caller: the user this credential acts as, the company it is bound to, how it is calling (REST or MCP; human, agent or service account) and the permissions it actually has here (the union of the user's roles' groups ∩ the credential's permissions). Call it first to know what you can do.\n\nPermission: `member`.", "tags": [ "Account" ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "object", "properties": { "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "email": { "type": "string" } }, "required": [ "firstName", "lastName", "email" ], "additionalProperties": false }, "company": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "shortName": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "shortName" ], "additionalProperties": false }, "actorType": { "type": "string", "enum": [ "human", "agent", "service" ] }, "channel": { "type": "string" }, "permissions": { "type": "array", "items": { "type": "string" } } }, "required": [ "user", "company", "actorType", "channel", "permissions" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "me.get", "x-eightyone-permission": "member", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/meters": { "get": { "operationId": "meters.list", "summary": "List machine meters", "description": "Usage meters on machines (run hours, strokes, cycles…) and their current readings. Usage-based maintenance rules open a task each time a meter advances by their interval. Filter by machine.\n\nPermission: `maintenance:view`.", "tags": [ "Machines" ], "parameters": [ { "name": "ssuId", "in": "query", "required": false, "description": "SSU external id", "schema": { "description": "SSU external id", "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ssuId": { "type": "string", "description": "SSU external id" }, "ssuName": { "type": [ "string", "null" ] }, "key": { "type": "string" }, "name": { "type": "string" }, "uom": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "manual", "signal" ], "description": "signal: counted from machine data; manual: people enter readings" }, "currentValue": { "type": "number" } }, "required": [ "id", "ssuId", "ssuName", "key", "name", "uom", "source", "currentValue" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "meters.list", "x-eightyone-permission": "maintenance:view", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/meters/{id}/readings": { "post": { "operationId": "meters.record_reading", "summary": "Record a meter reading", "description": "Enter a meter's current total (not the change), as a technician reads it off the machine. It can open usage-based maintenance tasks: preview it with dryRun first to see which. Needs 'Manage maintenance'.\n\nPermission: `maintenance:manage`.", "tags": [ "Machines" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Meter id (meters_list)" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "type": "number", "minimum": 0, "description": "The meter's reading: its running total" } }, "required": [ "value" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ssuId": { "type": "string", "description": "SSU external id" }, "ssuName": { "type": [ "string", "null" ] }, "key": { "type": "string" }, "name": { "type": "string" }, "uom": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "manual", "signal" ], "description": "signal: counted from machine data; manual: people enter readings" }, "currentValue": { "type": "number" } }, "required": [ "id", "ssuId", "ssuName", "key", "name", "uom", "source", "currentValue" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "meters.record_reading", "x-eightyone-permission": "maintenance:manage", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "preview" } }, "/api/v1/ncrs": { "post": { "operationId": "ncrs.open", "summary": "Open an NCR", "description": "Open a nonconformance report: a task of the company's NCR task type (Settings), linked to the task it was found on and carrying its machine and work order, with the affected lot or product recorded on it. A failed in-line check opens one by itself; use this for what people find. Disposition it with ncrs_disposition.\n\nPermission: `member`.", "tags": [ "Quality" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "description": "What's wrong, in a line" }, "details": { "description": "What was found: measurements, quantities, how it was noticed", "type": "string" }, "foundOn": { "description": "External id of the task it was found on (an operation or inspection): the NCR takes its machine and work order", "type": "string" }, "ssuId": { "description": "SSU external id, when not taken from foundOn", "type": "string" }, "workOrderId": { "description": "Work order external id, when not taken from foundOn", "type": "string" }, "lotCode": { "description": "The affected lot", "type": "string" }, "productSku": { "description": "The affected product", "type": "string" }, "priorityId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "assigneeIds": { "description": "Personnel ids", "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } }, "required": [ "title" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Task external id" }, "title": { "type": "string" }, "details": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "startDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "dueDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "priorityId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "typeId": { "description": "Task type external id", "type": [ "string", "null" ] }, "team": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "The team whose members see and take this task: its task type's team (change it on the type)" }, "ssuId": { "description": "SSU external id", "type": [ "string", "null" ] }, "externalSystemId": { "description": "Your id for the task", "type": [ "string", "null" ] }, "incompleteReason": { "type": [ "string", "null" ] }, "declinedReason": { "type": [ "string", "null" ] }, "isPartialCompletion": { "type": "boolean", "description": "Completed in part; a follow-up task carries the rest" }, "handoffRole": { "anyOf": [ { "type": "string", "enum": [ "proxy", "mirror" ] }, { "type": "null" } ], "description": "proxy: you sent it to a partner; mirror: a partner sent it to you" }, "problemCodeId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Failure coding: what was wrong" }, "causeCodeId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Failure coding: why" }, "remedyCodeId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Failure coding: what fixed it" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "foundOn": { "type": [ "string", "null" ] }, "lotCode": { "type": [ "string", "null" ] }, "productSku": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "details", "status", "startDate", "endDate", "dueDate", "priorityId", "typeId", "team", "ssuId", "externalSystemId", "incompleteReason", "declinedReason", "isPartialCompletion", "handoffRole", "problemCodeId", "causeCodeId", "remedyCodeId", "createdAt", "updatedAt", "foundOn", "lotCode", "productSku" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "ncrs.open", "x-eightyone-permission": "member", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "preview" } }, "/api/v1/ncrs/{id}/disposition": { "post": { "operationId": "ncrs.disposition", "summary": "Disposition an NCR", "description": "Decide what happens to nonconforming material, once per NCR. use_as_is: recorded only. rework: creates a rework task (of reworkTaskTypeId, or the NCR's own type). scrap: moves `quantity` of the lot to the bads bin and blocks the lot. return: blocks the lot for return to the vendor. Needs 'Disposition NCRs'.\n\nPermission: `ncr:disposition`.", "tags": [ "Quality" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "The NCR's task external id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "disposition": { "type": "string", "enum": [ "use_as_is", "rework", "scrap", "return" ] }, "lotCode": { "description": "The affected lot (scrap and return act on it)", "type": "string" }, "quantity": { "description": "For scrap: how much of the lot", "type": "number", "exclusiveMinimum": 0 }, "reworkTaskTypeId": { "description": "For rework: the task type's external id", "type": "string" }, "notes": { "type": "string", "maxLength": 2000 } }, "required": [ "disposition" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "disposition": { "type": "string", "enum": [ "use_as_is", "rework", "scrap", "return" ] }, "lot": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "status": { "type": "string" } }, "required": [ "code", "status" ], "additionalProperties": false }, { "type": "null" } ] }, "reworkTaskId": { "description": "The rework task's external id", "type": [ "string", "null" ] } }, "required": [ "id", "disposition", "lot", "reworkTaskId" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "ncrs.disposition", "x-eightyone-permission": "ncr:disposition", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "transactional" } }, "/api/v1/partner-deliveries": { "get": { "operationId": "partner_deliveries.list", "summary": "List partner deliveries", "description": "Goods sent to or received from partner companies, from your side.\n\nPermission: `handoffs:send`.", "tags": [ "Partner network" ], "parameters": [ { "name": "direction", "in": "query", "required": false, "schema": { "default": "all", "type": "string", "enum": [ "incoming", "outgoing", "all" ] } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "in_transit", "partially_received", "shortfall", "received", "reversed", "refused", "unmapped", "held", "settled" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "direction": { "type": "string", "enum": [ "incoming", "outgoing" ] }, "state": { "type": "string" }, "partner": { "type": "object", "properties": { "shortName": { "type": "string" }, "name": { "type": "string" } }, "required": [ "shortName", "name" ], "additionalProperties": false }, "taskId": { "type": [ "string", "null" ] }, "handoffId": { "type": [ "string", "null" ] }, "shipmentCode": { "type": [ "string", "null" ] }, "returnOf": { "type": [ "string", "null" ] }, "receivingStorageUnit": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "linkActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" }, "quantity": { "type": "number" }, "mode": { "type": "string" } }, "required": [ "id", "name", "quantity", "mode" ], "additionalProperties": {} } } }, "required": [ "id", "kind", "direction", "state", "partner", "taskId", "handoffId", "shipmentCode", "returnOf", "receivingStorageUnit", "linkActive", "createdAt", "lines" ], "additionalProperties": false } } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "partner_deliveries.list", "x-eightyone-permission": "handoffs:send", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/partner-deliveries/{id}": { "get": { "operationId": "partner_deliveries.get", "summary": "Get a partner delivery", "description": "One delivery from your side.\n\nPermission: `handoffs:send`.", "tags": [ "Partner network" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "direction": { "type": "string", "enum": [ "incoming", "outgoing" ] }, "state": { "type": "string" }, "partner": { "type": "object", "properties": { "shortName": { "type": "string" }, "name": { "type": "string" } }, "required": [ "shortName", "name" ], "additionalProperties": false }, "taskId": { "type": [ "string", "null" ] }, "handoffId": { "type": [ "string", "null" ] }, "shipmentCode": { "type": [ "string", "null" ] }, "returnOf": { "type": [ "string", "null" ] }, "receivingStorageUnit": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "linkActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" }, "quantity": { "type": "number" }, "mode": { "type": "string" } }, "required": [ "id", "name", "quantity", "mode" ], "additionalProperties": {} } } }, "required": [ "id", "kind", "direction", "state", "partner", "taskId", "handoffId", "shipmentCode", "returnOf", "receivingStorageUnit", "linkActive", "createdAt", "lines" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "partner_deliveries.get", "x-eightyone-permission": "handoffs:send", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/partner-deliveries/{id}/receive": { "post": { "operationId": "partner_deliveries.receive", "summary": "Receive a partner delivery", "description": "Book goods a partner sent you into stock, line by line (damaged quantities go to the bads bin), optionally reporting the rest missing.\n\nPermission: `handoffs:send + inventory:receive`.", "tags": [ "Partner network" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "default": [], "type": "array", "items": { "type": "object", "properties": { "lineId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "quantity": { "type": "number", "minimum": 0 }, "damagedQuantity": { "default": 0, "type": "number", "minimum": 0 }, "storageUnitId": { "description": "Your storage unit to receive into (default: the delivery's receiving location)", "type": "string" } }, "required": [ "lineId", "quantity" ] } }, "reportRestMissing": { "default": false, "type": "boolean" } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "direction": { "type": "string", "enum": [ "incoming", "outgoing" ] }, "state": { "type": "string" }, "partner": { "type": "object", "properties": { "shortName": { "type": "string" }, "name": { "type": "string" } }, "required": [ "shortName", "name" ], "additionalProperties": false }, "taskId": { "type": [ "string", "null" ] }, "handoffId": { "type": [ "string", "null" ] }, "shipmentCode": { "type": [ "string", "null" ] }, "returnOf": { "type": [ "string", "null" ] }, "receivingStorageUnit": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "linkActive": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string" }, "quantity": { "type": "number" }, "mode": { "type": "string" } }, "required": [ "id", "name", "quantity", "mode" ], "additionalProperties": {} } } }, "required": [ "id", "kind", "direction", "state", "partner", "taskId", "handoffId", "shipmentCode", "returnOf", "receivingStorageUnit", "linkActive", "createdAt", "lines" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "partner_deliveries.receive", "x-eightyone-permission": "handoffs:send + inventory:receive", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "transactional" } }, "/api/v1/purchase-orders": { "get": { "operationId": "purchase_orders.list", "summary": "List purchase orders", "description": "Purchase orders (purchase requests): vendor, status, and each line's product, quantity ordered and received. Quantities only: EightyOne holds no prices.\n\nPermission: `member`.", "tags": [ "Inventory" ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "e.g. open, partially_received, received", "schema": { "description": "e.g. open, partially_received, received", "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "vendor": { "type": [ "string", "null" ] }, "externalSystemId": { "type": [ "string", "null" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "lineId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sku": { "type": [ "string", "null" ] }, "product": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "uom": { "type": [ "string", "null" ] }, "receivedQuantity": { "type": "number" }, "expectedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "lineId", "sku", "product", "quantity", "uom", "receivedQuantity", "expectedAt" ], "additionalProperties": false } } }, "required": [ "id", "name", "status", "vendor", "externalSystemId", "lines" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "purchase_orders.list", "x-eightyone-permission": "member", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/purchase-orders/{id}/receive": { "post": { "operationId": "purchase_orders.receive", "summary": "Receive against a purchase order", "description": "Book what arrived: per PO line, the quantity and the storage unit it goes to (with the lot for lot-tracked products). An inspection plan for the product or vendor puts it in quarantine and opens an inspection task. Can't receive more than ordered. Needs 'Receive inventory'. Preview it first.\n\nPermission: `inventory:receive`.", "tags": [ "Inventory" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Purchase order id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "lines": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "lineId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "The PO line" }, "quantity": { "type": "number", "exclusiveMinimum": 0 }, "storageUnitId": { "type": "string", "description": "Where it goes: storage unit external id" }, "bin": { "type": "string", "enum": [ "goods", "bads", "quarantine" ] }, "lotCode": { "description": "Required for lot-tracked products", "type": "string" }, "quarantine": { "description": "Hold it for inspection", "type": "boolean" } }, "required": [ "lineId", "quantity", "storageUnitId" ], "additionalProperties": false } } }, "required": [ "lines" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "vendor": { "type": [ "string", "null" ] }, "externalSystemId": { "type": [ "string", "null" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "lineId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sku": { "type": [ "string", "null" ] }, "product": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "uom": { "type": [ "string", "null" ] }, "receivedQuantity": { "type": "number" }, "expectedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "lineId", "sku", "product", "quantity", "uom", "receivedQuantity", "expectedAt" ], "additionalProperties": false } } }, "required": [ "id", "name", "status", "vendor", "externalSystemId", "lines" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "purchase_orders.receive", "x-eightyone-permission": "inventory:receive", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "preview" } }, "/api/v1/reason-codes": { "get": { "operationId": "reason_codes.list", "summary": "List reason codes", "description": "The company's reason codes: why machines stop (downtime), failure problem / cause / remedy codes on maintenance tasks, scrap and stock-adjustment reasons.\n\nPermission: `member`.", "tags": [ "Machines" ], "parameters": [ { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "downtime", "failure_problem", "failure_cause", "failure_remedy", "scrap", "adjustment" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "kind": { "type": "string" }, "code": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "parentId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "isActive": { "type": "boolean" } }, "required": [ "id", "kind", "code", "label", "parentId", "isActive" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "reason_codes.list", "x-eightyone-permission": "member", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/shipments": { "get": { "operationId": "shipments.list", "summary": "List shipments", "description": "Shipments to customers, newest first: draft (being prepared), shipped or cancelled.\n\nPermission: `inventory:view`.", "tags": [ "Inventory" ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "shipped", "cancelled" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "status": { "type": "string", "description": "draft / shipped / cancelled" }, "customer": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "shipToAddress": { "type": [ "string", "null" ] }, "trackingReference": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "shippedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "partnerDeliveryState": { "description": "For a customer that is an EightyOne company", "type": [ "string", "null" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "storageUnitId": { "type": [ "string", "null" ] }, "lotCode": { "type": [ "string", "null" ] } }, "required": [ "sku", "quantity", "storageUnitId", "lotCode" ], "additionalProperties": false } } }, "required": [ "id", "code", "status", "customer", "shipToAddress", "trackingReference", "notes", "shippedAt", "partnerDeliveryState", "lines" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "shipments.list", "x-eightyone-permission": "inventory:view", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" }, "post": { "operationId": "shipments.create", "summary": "Prepare a shipment", "description": "Draft a shipment to a customer: per line the SKU, quantity and the storage unit it ships from (and the lot for lot-tracked products). Nothing leaves stock until shipments_ship. Factories only. Needs 'Manage inventory'.\n\nPermission: `inventory:manage`.", "tags": [ "Inventory" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "description": "Customer external id (customers_list)" }, "lines": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "quantity": { "type": "number", "exclusiveMinimum": 0 }, "storageUnitId": { "type": "string", "description": "Storage unit external id it ships from" }, "lotCode": { "type": "string" } }, "required": [ "sku", "quantity", "storageUnitId" ], "additionalProperties": false } }, "shipToAddress": { "description": "Defaults to the customer's", "type": "string" }, "code": { "type": "string" }, "trackingReference": { "type": "string" }, "notes": { "type": "string" } }, "required": [ "customerId", "lines" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "status": { "type": "string", "description": "draft / shipped / cancelled" }, "customer": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "shipToAddress": { "type": [ "string", "null" ] }, "trackingReference": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "shippedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "partnerDeliveryState": { "description": "For a customer that is an EightyOne company", "type": [ "string", "null" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "storageUnitId": { "type": [ "string", "null" ] }, "lotCode": { "type": [ "string", "null" ] } }, "required": [ "sku", "quantity", "storageUnitId", "lotCode" ], "additionalProperties": false } } }, "required": [ "id", "code", "status", "customer", "shipToAddress", "trackingReference", "notes", "shippedAt", "partnerDeliveryState", "lines" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "shipments.create", "x-eightyone-permission": "inventory:manage", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "transactional" } }, "/api/v1/shipments/{id}": { "get": { "operationId": "shipments.get", "summary": "Get a shipment", "description": "A shipment with its lines.\n\nPermission: `inventory:view`.", "tags": [ "Inventory" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Shipment external id" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "status": { "type": "string", "description": "draft / shipped / cancelled" }, "customer": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "shipToAddress": { "type": [ "string", "null" ] }, "trackingReference": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "shippedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "partnerDeliveryState": { "description": "For a customer that is an EightyOne company", "type": [ "string", "null" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "storageUnitId": { "type": [ "string", "null" ] }, "lotCode": { "type": [ "string", "null" ] } }, "required": [ "sku", "quantity", "storageUnitId", "lotCode" ], "additionalProperties": false } } }, "required": [ "id", "code", "status", "customer", "shipToAddress", "trackingReference", "notes", "shippedAt", "partnerDeliveryState", "lines" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "shipments.get", "x-eightyone-permission": "inventory:view", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/shipments/{id}/cancel": { "post": { "operationId": "shipments.cancel", "summary": "Cancel a draft shipment", "description": "Cancel a shipment that hasn't shipped. Nothing moves: a draft holds no stock. Needs 'Manage inventory'.\n\nPermission: `inventory:manage`.", "tags": [ "Inventory" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Shipment external id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "status": { "type": "string", "description": "draft / shipped / cancelled" }, "customer": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "shipToAddress": { "type": [ "string", "null" ] }, "trackingReference": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "shippedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "partnerDeliveryState": { "description": "For a customer that is an EightyOne company", "type": [ "string", "null" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "storageUnitId": { "type": [ "string", "null" ] }, "lotCode": { "type": [ "string", "null" ] } }, "required": [ "sku", "quantity", "storageUnitId", "lotCode" ], "additionalProperties": false } } }, "required": [ "id", "code", "status", "customer", "shipToAddress", "trackingReference", "notes", "shippedAt", "partnerDeliveryState", "lines" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "shipments.cancel", "x-eightyone-permission": "inventory:manage", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "transactional" } }, "/api/v1/shipments/{id}/ship": { "post": { "operationId": "shipments.ship", "summary": "Ship it", "description": "Confirm a draft shipment left: each line's goods come out of stock, written to the customer. For a customer that is an EightyOne company, the goods arrive in their transit. Refused if any line lacks the stock, names a lot that isn't available, or takes another customer's consigned stock. Needs 'Manage inventory'. Preview it first.\n\nPermission: `inventory:manage`.", "tags": [ "Inventory" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Shipment external id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "status": { "type": "string", "description": "draft / shipped / cancelled" }, "customer": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "shipToAddress": { "type": [ "string", "null" ] }, "trackingReference": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "shippedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "partnerDeliveryState": { "description": "For a customer that is an EightyOne company", "type": [ "string", "null" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "quantity": { "type": "number" }, "storageUnitId": { "type": [ "string", "null" ] }, "lotCode": { "type": [ "string", "null" ] } }, "required": [ "sku", "quantity", "storageUnitId", "lotCode" ], "additionalProperties": false } } }, "required": [ "id", "code", "status", "customer", "shipToAddress", "trackingReference", "notes", "shippedAt", "partnerDeliveryState", "lines" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "shipments.ship", "x-eightyone-permission": "inventory:manage", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "preview" } }, "/api/v1/ssus": { "get": { "operationId": "ssus.list", "summary": "List SSUs", "description": "The company's SSUs (sub-site units: machines, assets, locations within a site), newest first.\n\nPermission: `member`.", "tags": [ "SSUs" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size (1–100, default 50)", "schema": { "default": 50, "description": "Page size (1–100, default 50)", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Rows to skip", "schema": { "default": 0, "description": "Rows to skip", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "SSU external id (also its QR identity)" }, "name": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "isActive": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "location": { "anyOf": [ {}, { "type": "null" } ], "description": "GeoJSON point (PostGIS geometry), or null" }, "make": { "description": "Machine make, from the global machine catalog (factories)", "type": [ "string", "null" ] }, "model": { "description": "Machine model, from the global machine catalog", "type": [ "string", "null" ] }, "sku": { "description": "Model-level SKU / part number (not a serial number)", "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "imageUrl", "isActive", "isDefault", "location", "make", "model", "sku", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "offset", "total", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "ssus.list", "x-eightyone-permission": "member", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/ssus/{id}": { "get": { "operationId": "ssus.get", "summary": "Get an SSU", "description": "One SSU by its external id, with the company's guidance note on it for agents (if any): read it before drawing conclusions about this machine.\n\nPermission: `member`.", "tags": [ "SSUs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "SSU external id (also its QR identity)" }, "name": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "isActive": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "location": { "anyOf": [ {}, { "type": "null" } ], "description": "GeoJSON point (PostGIS geometry), or null" }, "make": { "description": "Machine make, from the global machine catalog (factories)", "type": [ "string", "null" ] }, "model": { "description": "Machine model, from the global machine catalog", "type": [ "string", "null" ] }, "sku": { "description": "Model-level SKU / part number (not a serial number)", "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "guidance": { "anyOf": [ { "type": "object", "properties": { "body": { "type": "string" }, "thresholds": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } } }, "required": [ "body", "thresholds" ], "additionalProperties": false }, { "type": "null" } ], "description": "What the company's administrators tell agents about this SSU" } }, "required": [ "id", "name", "imageUrl", "isActive", "isDefault", "location", "make", "model", "sku", "createdAt", "updatedAt", "guidance" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "ssus.get", "x-eightyone-permission": "member", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" }, "put": { "operationId": "ssus.update", "summary": "Update an SSU", "description": "Change an SSU's name, image, active flag, default flag or location. Making it the default unsets the default on the other SSUs of its sites.\n\nPermission: `clients:manage`.", "tags": [ "SSUs" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "imageUrl": { "type": "string" }, "isActive": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "location": { "type": "object", "properties": { "longitude": { "type": "number", "minimum": -180, "maximum": 180 }, "latitude": { "type": "number", "minimum": -90, "maximum": 90 } }, "required": [ "longitude", "latitude" ] } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "SSU external id (also its QR identity)" }, "name": { "type": "string" }, "imageUrl": { "type": [ "string", "null" ] }, "isActive": { "type": "boolean" }, "isDefault": { "type": "boolean" }, "location": { "anyOf": [ {}, { "type": "null" } ], "description": "GeoJSON point (PostGIS geometry), or null" }, "make": { "description": "Machine make, from the global machine catalog (factories)", "type": [ "string", "null" ] }, "model": { "description": "Machine model, from the global machine catalog", "type": [ "string", "null" ] }, "sku": { "description": "Model-level SKU / part number (not a serial number)", "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "imageUrl", "isActive", "isDefault", "location", "make", "model", "sku", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "ssus.update", "x-eightyone-permission": "clients:manage", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "transactional" } }, "/api/v1/stock-transactions": { "get": { "operationId": "stock_transactions.list", "summary": "Export stock movements", "description": "The stock movement ledger (consumption, receipts, transfers, shipments), newest first, for pull-based ERP sync. Quantities only.\n\nPermission: `inventory:view`.", "tags": [ "Inventory" ], "parameters": [ { "name": "from", "in": "query", "required": false, "description": "Movements at or after this time", "schema": { "description": "Movements at or after this time", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, { "name": "to", "in": "query", "required": false, "description": "Movements before this time", "schema": { "description": "Movements before this time", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 1000, "type": "integer", "minimum": 1, "maximum": 5000 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "time": { "type": "string", "format": "date-time" }, "quantity": { "type": "number" }, "bin": { "description": "goods, bads, installed, transit, quarantine", "type": [ "string", "null" ] }, "itemId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Line item (unit) id" }, "fromStorageUnitId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "toStorageUnitId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "fromVendorId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "toVendorId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "toClientId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "toCustomerId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "taskId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "lotId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "serialId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "reasonCodeId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "stockTransactionGroupId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "time", "quantity", "bin", "itemId", "fromStorageUnitId", "toStorageUnitId", "fromVendorId", "toVendorId", "toClientId", "toCustomerId", "taskId", "lotId", "serialId", "reasonCodeId", "stockTransactionGroupId" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "stock_transactions.list", "x-eightyone-permission": "inventory:view", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/stock/transfers": { "post": { "operationId": "stock.transfer", "summary": "Move stock", "description": "Move stock between storage units, or between bins in one unit, as the dashboard's transfers do: name the product by SKU, and the lot or serial when it's tracked. It can't move more than is there. Needs 'Manage inventory'.\n\nPermission: `inventory:manage`.", "tags": [ "Inventory" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sku": { "type": "string" }, "quantity": { "type": "number", "exclusiveMinimum": 0 }, "from": { "type": "string", "description": "Storage unit external id it leaves" }, "to": { "type": "string", "description": "Storage unit external id it goes to" }, "bin": { "default": "goods", "description": "The bin it's taken from", "type": "string", "enum": [ "goods", "bads", "quarantine" ] }, "toBin": { "description": "The bin it lands in (default: the same)", "type": "string", "enum": [ "goods", "bads", "quarantine" ] }, "lotCode": { "description": "Which lot, for lot-tracked products", "type": "string" }, "serialCode": { "description": "Which unit, for serialized products", "type": "string" } }, "required": [ "sku", "quantity", "from", "to" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "sku": { "type": "string" }, "quantity": { "type": "number" }, "from": { "type": "object", "properties": { "id": { "type": "string", "description": "Storage unit external id" }, "name": { "type": "string" }, "site": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" } }, "required": [ "id", "name", "kind" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "name", "site" ], "additionalProperties": false }, "to": { "type": "object", "properties": { "id": { "type": "string", "description": "Storage unit external id" }, "name": { "type": "string" }, "site": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" } }, "required": [ "id", "name", "kind" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "name", "site" ], "additionalProperties": false }, "bin": { "type": "string" }, "toBin": { "type": "string" }, "lotCode": { "type": [ "string", "null" ] } }, "required": [ "sku", "quantity", "from", "to", "bin", "toBin", "lotCode" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "stock.transfer", "x-eightyone-permission": "inventory:manage", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "preview" } }, "/api/v1/storage-units": { "get": { "operationId": "storage_units.list", "summary": "List storage units", "description": "Where stock sits: each storage unit (shelf, rack, bay, dock…) with its storage site and whose it is: warehouse or site (the company's own), client, personnel (a technician's van), customer_consigned, partner.\n\nPermission: `inventory:view`.", "tags": [ "Inventory" ], "parameters": [ { "name": "storageSiteId", "in": "query", "required": false, "description": "Storage site external id", "schema": { "description": "Storage site external id", "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Storage unit external id" }, "name": { "type": "string" }, "site": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" } }, "required": [ "id", "name", "kind" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "name", "site" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "storage_units.list", "x-eightyone-permission": "inventory:view", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/storage-units/{id}": { "get": { "operationId": "storage_units.get", "summary": "What's in a storage unit", "description": "A storage unit and everything in it: per product, bin (goods / bads / quarantine), lot and serial.\n\nPermission: `inventory:view`.", "tags": [ "Inventory" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Storage unit external id" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Storage unit external id" }, "name": { "type": "string" }, "site": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "kind": { "type": "string" } }, "required": [ "id", "name", "kind" ], "additionalProperties": false }, { "type": "null" } ] }, "contents": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "product": { "type": [ "string", "null" ] }, "bin": { "type": [ "string", "null" ] }, "lotCode": { "type": [ "string", "null" ] }, "serialCode": { "type": [ "string", "null" ] }, "quantity": { "type": "number" } }, "required": [ "sku", "product", "bin", "lotCode", "serialCode", "quantity" ], "additionalProperties": false } } }, "required": [ "id", "name", "site", "contents" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "storage_units.get", "x-eightyone-permission": "inventory:view", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/storylines/ssus/{id}": { "get": { "operationId": "storylines.ssu", "summary": "A machine's story", "description": "What happened on one machine (SSU) in a window (default: the last 7 days), as a chronological narrative: orders run, stops and their reasons, maintenance done, scrap and NCRs, meter readings, plus headline numbers. The best way to explain a machine's downtime.\n\nPermission: `maintenance:view`.", "tags": [ "Storylines" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "SSU external id" } }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "plotPoints": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The story's headline numbers" }, "chapters": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "events": { "type": "array", "items": { "type": "object", "properties": { "ts": { "type": "string", "format": "date-time" }, "kind": { "type": "string" }, "sentence": { "type": "string" } }, "required": [ "ts", "kind", "sentence" ], "additionalProperties": false } } }, "required": [ "title", "events" ], "additionalProperties": false } } }, "required": [ "subject", "plotPoints", "chapters" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "storylines.ssu", "x-eightyone-permission": "maintenance:view", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/storylines/work-orders/{id}": { "get": { "operationId": "storylines.work_order", "summary": "A work order's story", "description": "The life of one work order as a narrative: release, each operation started and finished, what was consumed and produced, scrap, quality checks and NCRs, shipment; with lead time and yield.\n\nPermission: `production:view`.", "tags": [ "Storylines" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Work order external id" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "plotPoints": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {}, "description": "The story's headline numbers" }, "chapters": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "events": { "type": "array", "items": { "type": "object", "properties": { "ts": { "type": "string", "format": "date-time" }, "kind": { "type": "string" }, "sentence": { "type": "string" } }, "required": [ "ts", "kind", "sentence" ], "additionalProperties": false } } }, "required": [ "title", "events" ], "additionalProperties": false } } }, "required": [ "subject", "plotPoints", "chapters" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "storylines.work_order", "x-eightyone-permission": "production:view", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/task-types": { "get": { "operationId": "task_types.list", "summary": "List task types", "description": "The company's task types: the templates every task is created from (work orders' operations, maintenance, NCRs, inspections, approvals…), alphabetically. Use a type's `id` as `typeId` when creating a task.\n\nPermission: `member`.", "tags": [ "Task types" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size (1–100, default 50)", "schema": { "default": 50, "description": "Page size (1–100, default 50)", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Rows to skip", "schema": { "default": 0, "description": "Rows to skip", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Task type external id" }, "typeName": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "isQuote": { "type": "boolean" }, "isUserGenerated": { "type": "boolean", "description": "Field users may create tasks of this type themselves" }, "isDataRequest": { "type": "boolean", "description": "Tasks of this type ask a partner company for traceability data" }, "isRemote": { "type": "boolean" }, "isInventory": { "type": "boolean" }, "defaultUseTransit": { "type": "boolean", "description": "Inventory tasks stage stock through the transit bin by default" }, "isBulk": { "type": "boolean" }, "workCenterId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "team": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "The team whose members see and take this type's tasks. Changing it moves every task of the type" }, "parentProductId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The product a production operation of this type makes" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "typeName", "color", "isQuote", "isUserGenerated", "isDataRequest", "isRemote", "isInventory", "defaultUseTransit", "isBulk", "workCenterId", "team", "parentProductId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "offset", "total", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "task_types.list", "x-eightyone-permission": "member", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/task-types/{id}": { "get": { "operationId": "task_types.get", "summary": "Get a task type", "description": "One task type by its id.\n\nPermission: `member`.", "tags": [ "Task types" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Task type external id" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Task type external id" }, "typeName": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "isQuote": { "type": "boolean" }, "isUserGenerated": { "type": "boolean", "description": "Field users may create tasks of this type themselves" }, "isDataRequest": { "type": "boolean", "description": "Tasks of this type ask a partner company for traceability data" }, "isRemote": { "type": "boolean" }, "isInventory": { "type": "boolean" }, "defaultUseTransit": { "type": "boolean", "description": "Inventory tasks stage stock through the transit bin by default" }, "isBulk": { "type": "boolean" }, "workCenterId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "team": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "The team whose members see and take this type's tasks. Changing it moves every task of the type" }, "parentProductId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The product a production operation of this type makes" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "typeName", "color", "isQuote", "isUserGenerated", "isDataRequest", "isRemote", "isInventory", "defaultUseTransit", "isBulk", "workCenterId", "team", "parentProductId", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "task_types.get", "x-eightyone-permission": "member", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/tasks": { "get": { "operationId": "tasks.list", "summary": "List tasks", "description": "Tasks, newest first. Everything in EightyOne is a task (work-order operations, maintenance, inspections, NCRs, approvals…). Open tasks only unless a status is given or includeCompleted=true. Without the 'See all tasks' permission you see only tasks assigned to you, plus your teams' tasks with 'See tasks for my team'.\n\nPermission: `member`.", "tags": [ "Tasks" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size (1–100, default 50)", "schema": { "default": 50, "description": "Page size (1–100, default 50)", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Rows to skip", "schema": { "default": 0, "description": "Rows to skip", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "preparation", "ready", "dispatched", "submitted", "incomplete", "done", "declined" ] } }, { "name": "typeId", "in": "query", "required": false, "description": "Task type external id", "schema": { "description": "Task type external id", "type": "string" } }, { "name": "ssuId", "in": "query", "required": false, "description": "SSU external id", "schema": { "description": "SSU external id", "type": "string" } }, { "name": "includeCompleted", "in": "query", "required": false, "description": "Include done and declined tasks", "schema": { "description": "Include done and declined tasks", "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Task external id" }, "title": { "type": "string" }, "details": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "startDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "dueDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "priorityId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "typeId": { "description": "Task type external id", "type": [ "string", "null" ] }, "team": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "The team whose members see and take this task: its task type's team (change it on the type)" }, "ssuId": { "description": "SSU external id", "type": [ "string", "null" ] }, "externalSystemId": { "description": "Your id for the task", "type": [ "string", "null" ] }, "incompleteReason": { "type": [ "string", "null" ] }, "declinedReason": { "type": [ "string", "null" ] }, "isPartialCompletion": { "type": "boolean", "description": "Completed in part; a follow-up task carries the rest" }, "handoffRole": { "anyOf": [ { "type": "string", "enum": [ "proxy", "mirror" ] }, { "type": "null" } ], "description": "proxy: you sent it to a partner; mirror: a partner sent it to you" }, "problemCodeId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Failure coding: what was wrong" }, "causeCodeId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Failure coding: why" }, "remedyCodeId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Failure coding: what fixed it" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "details", "status", "startDate", "endDate", "dueDate", "priorityId", "typeId", "team", "ssuId", "externalSystemId", "incompleteReason", "declinedReason", "isPartialCompletion", "handoffRole", "problemCodeId", "causeCodeId", "remedyCodeId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "offset", "total", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "tasks.list", "x-eightyone-permission": "member", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" }, "post": { "operationId": "tasks.create", "summary": "Create a task", "description": "Create a task of a task type, exactly as the dashboard does: the type's defaults apply (SLA due date, default assignee, transit, created-as-ready), and the task.created webhook fires. Needs 'Create tasks' unless the type is user-generated.\n\nPermission: `member`.", "tags": [ "Tasks" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "typeId": { "type": "string", "description": "Task type external id" }, "title": { "type": "string", "minLength": 1 }, "details": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "preparation", "ready", "dispatched", "submitted", "incomplete", "done" ] }, "startDate": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] }, "endDate": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] }, "dueDate": { "description": "Defaults to the type's SLA for the priority", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] }, "priorityId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ssuId": { "description": "SSU external id", "type": "string" }, "externalSystemId": { "type": "string" }, "fromStorageUnitId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "toStorageUnitId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "fromVendorId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "toVendorId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "assigneeIds": { "description": "Personnel ids", "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "incompleteReason": { "description": "Required when status is 'incomplete'", "type": "string" }, "after": { "description": "Link the new task to an existing one: dependency (it waits for that task) or follow", "type": "object", "properties": { "taskId": { "type": "string", "description": "An existing task's external id" }, "type": { "type": "string", "enum": [ "dependency", "follow" ] } }, "required": [ "taskId", "type" ], "additionalProperties": false } }, "required": [ "typeId", "title" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Task external id" }, "title": { "type": "string" }, "details": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "startDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "dueDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "priorityId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "typeId": { "description": "Task type external id", "type": [ "string", "null" ] }, "team": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "The team whose members see and take this task: its task type's team (change it on the type)" }, "ssuId": { "description": "SSU external id", "type": [ "string", "null" ] }, "externalSystemId": { "description": "Your id for the task", "type": [ "string", "null" ] }, "incompleteReason": { "type": [ "string", "null" ] }, "declinedReason": { "type": [ "string", "null" ] }, "isPartialCompletion": { "type": "boolean", "description": "Completed in part; a follow-up task carries the rest" }, "handoffRole": { "anyOf": [ { "type": "string", "enum": [ "proxy", "mirror" ] }, { "type": "null" } ], "description": "proxy: you sent it to a partner; mirror: a partner sent it to you" }, "problemCodeId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Failure coding: what was wrong" }, "causeCodeId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Failure coding: why" }, "remedyCodeId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Failure coding: what fixed it" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "details", "status", "startDate", "endDate", "dueDate", "priorityId", "typeId", "team", "ssuId", "externalSystemId", "incompleteReason", "declinedReason", "isPartialCompletion", "handoffRole", "problemCodeId", "causeCodeId", "remedyCodeId", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "tasks.create", "x-eightyone-permission": "member", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "preview" } }, "/api/v1/tasks/{from}/connections": { "post": { "operationId": "tasks.connect", "summary": "Connect two tasks", "description": "Link two tasks. 'dependency': the second waits for the first. It can't progress until the first is done, and goes back to open if it was already ready or dispatched (it becomes ready if the first is already done). 'follow': only records that the second follows the first. Connections are removed in the dashboard.\n\nPermission: `member`.", "tags": [ "Tasks" ], "parameters": [ { "name": "from", "in": "path", "required": true, "schema": { "type": "string", "description": "The first task's external id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "type": "string", "description": "The external id of the task that waits for or follows it" }, "type": { "type": "string", "enum": [ "dependency", "follow" ] }, "description": { "type": "string", "maxLength": 500 } }, "required": [ "to", "type" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "type": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "toStatus": { "type": "string", "description": "The second task's status after connecting" } }, "required": [ "from", "to", "type", "description", "toStatus" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "tasks.connect", "x-eightyone-permission": "member", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "transactional" } }, "/api/v1/tasks/{id}": { "get": { "operationId": "tasks.get", "summary": "Get a task", "description": "One task by its id.\n\nPermission: `member`.", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Task external id" }, "title": { "type": "string" }, "details": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "startDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "dueDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "priorityId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "typeId": { "description": "Task type external id", "type": [ "string", "null" ] }, "team": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "The team whose members see and take this task: its task type's team (change it on the type)" }, "ssuId": { "description": "SSU external id", "type": [ "string", "null" ] }, "externalSystemId": { "description": "Your id for the task", "type": [ "string", "null" ] }, "incompleteReason": { "type": [ "string", "null" ] }, "declinedReason": { "type": [ "string", "null" ] }, "isPartialCompletion": { "type": "boolean", "description": "Completed in part; a follow-up task carries the rest" }, "handoffRole": { "anyOf": [ { "type": "string", "enum": [ "proxy", "mirror" ] }, { "type": "null" } ], "description": "proxy: you sent it to a partner; mirror: a partner sent it to you" }, "problemCodeId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Failure coding: what was wrong" }, "causeCodeId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Failure coding: why" }, "remedyCodeId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Failure coding: what fixed it" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "details", "status", "startDate", "endDate", "dueDate", "priorityId", "typeId", "team", "ssuId", "externalSystemId", "incompleteReason", "declinedReason", "isPartialCompletion", "handoffRole", "problemCodeId", "causeCodeId", "remedyCodeId", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "tasks.get", "x-eightyone-permission": "member", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" }, "patch": { "operationId": "tasks.update", "summary": "Update a task", "description": "Change a task, with the dashboard's rules: status changes need 'Change task status from mobile' (assignees may still complete their own work), reassigning needs 'Reassign tasks', blocked tasks can't progress, producing tasks complete with goodQuantity / scrapQuantity (counts during the run: tasks_record_counts), maintenance types may need failure codes (problemCodeId, causeCodeId, remedyCodeId) to complete, 'incomplete' needs a reason and can create a follow-up (createFollowUp), 'declined' needs a reason. Tasks sent to a partner only accept details, dueDate and priorityId.\n\nPermission: `member`.", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "details": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "preparation", "ready", "dispatched", "submitted", "incomplete", "done", "declined" ] }, "startDate": { "anyOf": [ { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] }, { "type": "null" } ] }, "endDate": { "anyOf": [ { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] }, { "type": "null" } ] }, "dueDate": { "anyOf": [ { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] }, { "type": "null" } ] }, "priorityId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ssuId": { "description": "SSU external id, or null to clear", "type": [ "string", "null" ] }, "externalSystemId": { "type": "string" }, "assigneeIds": { "description": "Personnel ids: replaces the assignees", "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "incompleteReason": { "type": "string" }, "declinedReason": { "type": "string" }, "createFollowUp": { "description": "With status 'incomplete': create a follow-up task for the rest", "type": "boolean" }, "goodQuantity": { "type": "number", "minimum": 0 }, "scrapQuantity": { "type": "number", "minimum": 0 }, "scrapReasonCodeId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "problemCodeId": { "description": "Failure coding (reason_codes_list kind failure_problem); types that require it can't complete without all three", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "causeCodeId": { "description": "Failure coding: kind failure_cause", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "remedyCodeId": { "description": "Failure coding: kind failure_remedy", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Task external id" }, "title": { "type": "string" }, "details": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "startDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "dueDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "priorityId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "typeId": { "description": "Task type external id", "type": [ "string", "null" ] }, "team": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "The team whose members see and take this task: its task type's team (change it on the type)" }, "ssuId": { "description": "SSU external id", "type": [ "string", "null" ] }, "externalSystemId": { "description": "Your id for the task", "type": [ "string", "null" ] }, "incompleteReason": { "type": [ "string", "null" ] }, "declinedReason": { "type": [ "string", "null" ] }, "isPartialCompletion": { "type": "boolean", "description": "Completed in part; a follow-up task carries the rest" }, "handoffRole": { "anyOf": [ { "type": "string", "enum": [ "proxy", "mirror" ] }, { "type": "null" } ], "description": "proxy: you sent it to a partner; mirror: a partner sent it to you" }, "problemCodeId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Failure coding: what was wrong" }, "causeCodeId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Failure coding: why" }, "remedyCodeId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Failure coding: what fixed it" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "_meta": { "type": "object", "properties": { "previousStatus": { "type": "string" }, "statusChanged": { "type": "boolean" }, "followUpTaskId": { "type": "string" } }, "required": [ "previousStatus", "statusChanged" ], "additionalProperties": false } }, "required": [ "id", "title", "details", "status", "startDate", "endDate", "dueDate", "priorityId", "typeId", "team", "ssuId", "externalSystemId", "incompleteReason", "declinedReason", "isPartialCompletion", "handoffRole", "problemCodeId", "causeCodeId", "remedyCodeId", "createdAt", "updatedAt", "_meta" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "tasks.update", "x-eightyone-permission": "member", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "preview" }, "delete": { "operationId": "tasks.delete", "summary": "Delete a task", "description": "Delete a task, as the dashboard does: a task you sent to a partner withdraws the handoff; a task a partner sent you can't be deleted (decline it instead).\n\nPermission: `tasks:delete`.", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "204": { "description": "Success", "content": { "application/json": { "schema": { "type": "null" } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "tasks.delete", "x-eightyone-permission": "tasks:delete", "x-eightyone-effect": "destructive", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "unsupported" } }, "/api/v1/tasks/{id}/counts": { "post": { "operationId": "tasks.record_counts", "summary": "Record production counts", "description": "Add good and scrap quantities to a running work-order operation or producing task, as operators do from the app. Counts add up and feed OEE; the output posts to stock once, when the task completes. To count at completion instead, pass goodQuantity / scrapQuantity to tasks.update with the status.\n\nPermission: `member`.", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Task external id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "goodQuantity": { "type": "number", "minimum": 0 }, "scrapQuantity": { "type": "number", "minimum": 0 }, "scrapReasonCodeId": { "description": "A scrap reason (reason_codes_list, kind scrap)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "goodQuantity": { "type": "number" }, "scrapQuantity": { "type": "number" }, "scrapReasonCodeId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "goodQuantity", "scrapQuantity", "scrapReasonCodeId" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "tasks.record_counts", "x-eightyone-permission": "member", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "transactional" } }, "/api/v1/tasks/{id}/form": { "get": { "operationId": "tasks.get_form", "summary": "A task's form", "description": "The fields a task's form records, in order: type, whether it's required, the choices of a select, the limits of a measurement, whether a condition hides it, and the current answer. Answer them with tasks_submit_form.\n\nPermission: `member`.", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Task external id" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "The field's title: answer by it" }, "type": { "type": "string" }, "required": { "type": "boolean" }, "fillable": { "type": "boolean", "description": "false: photos, signatures, scans, stock and location fields are filled in the app" }, "visible": { "type": "boolean", "description": "false while its show-when condition isn't met (then it's never required)" }, "choices": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "For select fields: the allowed answers" }, "limits": { "anyOf": [ { "type": "object", "properties": { "lsl": { "type": [ "number", "null" ] }, "usl": { "type": [ "number", "null" ] }, "target": { "type": [ "number", "null" ] }, "uom": { "type": [ "string", "null" ] } }, "required": [ "lsl", "usl", "target", "uom" ], "additionalProperties": false }, { "type": "null" } ], "description": "For number fields: a value outside lsl–usl fails the check and opens an NCR" }, "value": { "description": "The current answer, if any" } }, "required": [ "title", "type", "required", "fillable", "visible", "choices", "limits", "value" ], "additionalProperties": false } } }, "required": [ "id", "fields" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "tasks.get_form", "x-eightyone-permission": "member", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" }, "post": { "operationId": "tasks.submit_form", "summary": "Fill in a task's form", "description": "Answer a task's form fields by title (tasks_get_form lists them), and optionally complete the task (status done or submitted) or mark it incomplete, as the app does. Completing needs every required field; measurements outside their limits open an NCR; machine-status fields set the machine's status. Counts and failure codes go with the completion, as in tasks_update. Preview it first.\n\nPermission: `member`.", "tags": [ "Tasks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Task external id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "answers": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "value": { "type": [ "string", "number", "boolean", "null" ] } }, "required": [ "title", "value" ] }, "description": "Answers by field title; fields left out keep their answer" }, "status": { "description": "Complete it (done, or submitted for review) or mark it incomplete; leave out to only save the answers", "type": "string", "enum": [ "done", "submitted", "incomplete" ] }, "incompleteReason": { "type": "string" }, "createFollowUp": { "type": "boolean" }, "goodQuantity": { "type": "number", "minimum": 0 }, "scrapQuantity": { "type": "number", "minimum": 0 }, "scrapReasonCodeId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "problemCodeId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "causeCodeId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "remedyCodeId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "answers" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Task external id" }, "title": { "type": "string" }, "details": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "startDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "dueDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "priorityId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "typeId": { "description": "Task type external id", "type": [ "string", "null" ] }, "team": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "The team whose members see and take this task: its task type's team (change it on the type)" }, "ssuId": { "description": "SSU external id", "type": [ "string", "null" ] }, "externalSystemId": { "description": "Your id for the task", "type": [ "string", "null" ] }, "incompleteReason": { "type": [ "string", "null" ] }, "declinedReason": { "type": [ "string", "null" ] }, "isPartialCompletion": { "type": "boolean", "description": "Completed in part; a follow-up task carries the rest" }, "handoffRole": { "anyOf": [ { "type": "string", "enum": [ "proxy", "mirror" ] }, { "type": "null" } ], "description": "proxy: you sent it to a partner; mirror: a partner sent it to you" }, "problemCodeId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Failure coding: what was wrong" }, "causeCodeId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Failure coding: why" }, "remedyCodeId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Failure coding: what fixed it" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "failedChecks": { "type": "array", "items": { "type": "string" } }, "ncrId": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "details", "status", "startDate", "endDate", "dueDate", "priorityId", "typeId", "team", "ssuId", "externalSystemId", "incompleteReason", "declinedReason", "isPartialCompletion", "handoffRole", "problemCodeId", "causeCodeId", "remedyCodeId", "createdAt", "updatedAt", "failedChecks", "ncrId" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "tasks.submit_form", "x-eightyone-permission": "member", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "preview" } }, "/api/v1/teams": { "get": { "operationId": "teams.list", "summary": "List teams", "description": "The company's teams, alphabetically, with their members' personnel ids. A task belongs to its task type's team: team members with 'See tasks for my team' see those tasks and can take them in the field.\n\nPermission: `member`.", "tags": [ "Teams" ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Team id" }, "name": { "type": "string" }, "color": { "type": "string" }, "memberIds": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": "Personnel ids of the members" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "color", "memberIds", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "teams.list", "x-eightyone-permission": "member", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" }, "post": { "operationId": "teams.create", "summary": "Create a team", "description": "Create a team, optionally with its members. Point task types at it to give it work.\n\nPermission: `settings:manage`.", "tags": [ "Teams" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Hex color, e.g. #026485" }, "memberIds": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": "Personnel ids: replaces the members" } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Team id" }, "name": { "type": "string" }, "color": { "type": "string" }, "memberIds": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": "Personnel ids of the members" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "color", "memberIds", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "teams.create", "x-eightyone-permission": "settings:manage", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "transactional" } }, "/api/v1/teams/{id}": { "patch": { "operationId": "teams.update", "summary": "Update a team", "description": "Rename or recolor a team, or replace its members (memberIds). Only the fields sent change. Members see the team's tasks at once.\n\nPermission: `settings:manage`.", "tags": [ "Teams" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$", "description": "Hex color, e.g. #026485" }, "memberIds": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": "Personnel ids: replaces the members" } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Team id" }, "name": { "type": "string" }, "color": { "type": "string" }, "memberIds": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": "Personnel ids of the members" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "color", "memberIds", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "teams.update", "x-eightyone-permission": "settings:manage", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "transactional" }, "delete": { "operationId": "teams.delete", "summary": "Delete a team", "description": "Delete a team and its memberships. Refused while a task type still belongs to it: move those types to another team (or none) first.\n\nPermission: `settings:manage`.", "tags": [ "Teams" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "responses": { "204": { "description": "Success", "content": { "application/json": { "schema": { "type": "null" } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "teams.delete", "x-eightyone-permission": "settings:manage", "x-eightyone-effect": "destructive", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "transactional" } }, "/api/v1/webhooks": { "get": { "operationId": "webhooks.list", "summary": "List webhooks", "description": "The company's webhook subscriptions.\n\nPermission: `api_keys:view`.", "tags": [ "Webhooks" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Page size (1–100, default 50)", "schema": { "default": 50, "description": "Page size (1–100, default 50)", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Rows to skip", "schema": { "default": 0, "description": "Rows to skip", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "isActive", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "targetUrl": { "type": "string" }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "isActive": { "type": "boolean" }, "failureCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "disabledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Set when repeated failures switched the webhook off" }, "headers": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "targetUrl", "eventTypes", "isActive", "failureCount", "disabledAt", "headers", "createdAt", "updatedAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "offset", "total", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "webhooks.list", "x-eightyone-permission": "api_keys:view", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" }, "post": { "operationId": "webhooks.create", "summary": "Create a webhook", "description": "Subscribe a URL to events. Deliveries are Standard Webhooks messages signed with EightyOne's Ed25519 key: verify them with the public keys at /api/v1/webhook-signing-keys. There is no secret to store.\n\nPermission: `webhooks:manage`.", "tags": [ "Webhooks" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "targetUrl": { "type": "string", "format": "uri", "description": "HTTPS endpoint; private and internal addresses are refused" }, "eventTypes": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "task.status_changed", "task.created", "client.created", "work_order.released", "work_order.completed", "downtime.started", "downtime.ended", "lot.created", "stock.reorder_triggered", "handoff.received", "handoff.status_changed", "handoff.declined", "handoff.deleted", "partner_delivery.incoming", "partner_delivery.received", "partner_delivery.shortfall", "data_package.received" ] } }, "headers": { "description": "Extra headers sent with each delivery", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } } }, "required": [ "name", "targetUrl", "eventTypes" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "targetUrl": { "type": "string" }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "isActive": { "type": "boolean" }, "failureCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "disabledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Set when repeated failures switched the webhook off" }, "headers": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "verification": { "type": "object", "properties": { "scheme": { "type": "string" }, "publicKeysUrl": { "type": "string" }, "headers": { "type": "array", "items": { "type": "string" } } }, "required": [ "scheme", "publicKeysUrl", "headers" ], "additionalProperties": false, "description": "Verify each delivery's signature with EightyOne's public key" } }, "required": [ "id", "name", "targetUrl", "eventTypes", "isActive", "failureCount", "disabledAt", "headers", "createdAt", "updatedAt", "verification" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "webhooks.create", "x-eightyone-permission": "webhooks:manage", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "unsupported" } }, "/api/v1/webhooks/{id}": { "get": { "operationId": "webhooks.get", "summary": "Get a webhook", "description": "One webhook subscription.\n\nPermission: `api_keys:view`.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "targetUrl": { "type": "string" }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "isActive": { "type": "boolean" }, "failureCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "disabledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Set when repeated failures switched the webhook off" }, "headers": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "targetUrl", "eventTypes", "isActive", "failureCount", "disabledAt", "headers", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "webhooks.get", "x-eightyone-permission": "api_keys:view", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" }, "patch": { "operationId": "webhooks.update", "summary": "Update a webhook", "description": "Change a webhook's name, URL, events, headers or active flag.\n\nPermission: `webhooks:manage`.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "targetUrl": { "type": "string", "format": "uri" }, "eventTypes": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "task.status_changed", "task.created", "client.created", "work_order.released", "work_order.completed", "downtime.started", "downtime.ended", "lot.created", "stock.reorder_triggered", "handoff.received", "handoff.status_changed", "handoff.declined", "handoff.deleted", "partner_delivery.incoming", "partner_delivery.received", "partner_delivery.shortfall", "data_package.received" ] } }, "isActive": { "type": "boolean" }, "headers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } } }, "required": [], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "targetUrl": { "type": "string" }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "isActive": { "type": "boolean" }, "failureCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "disabledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Set when repeated failures switched the webhook off" }, "headers": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "targetUrl", "eventTypes", "isActive", "failureCount", "disabledAt", "headers", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "webhooks.update", "x-eightyone-permission": "webhooks:manage", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "unsupported" }, "delete": { "operationId": "webhooks.delete", "summary": "Delete a webhook", "description": "Remove a webhook subscription.\n\nPermission: `webhooks:manage`.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "204": { "description": "Success", "content": { "application/json": { "schema": { "type": "null" } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "webhooks.delete", "x-eightyone-permission": "webhooks:manage", "x-eightyone-effect": "destructive", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "unsupported" } }, "/api/v1/webhooks/{id}/logs": { "get": { "operationId": "webhooks.delivery_logs", "summary": "Webhook delivery log", "description": "Recent deliveries of one webhook with their status, response and timing.\n\nPermission: `api_keys:view`.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1–100, default 50)", "schema": { "default": 50, "description": "Page size (1–100, default 50)", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "offset", "in": "query", "required": false, "description": "Rows to skip", "schema": { "default": 0, "description": "Rows to skip", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "success", "failed", "retrying" ] } }, { "name": "eventType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "task.status_changed", "task.created", "client.created", "work_order.released", "work_order.completed", "downtime.started", "downtime.ended", "lot.created", "stock.reorder_triggered", "handoff.received", "handoff.status_changed", "handoff.declined", "handoff.deleted", "partner_delivery.incoming", "partner_delivery.received", "partner_delivery.shortfall", "data_package.received" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "eventType": { "type": "string" }, "eventId": { "type": "string" }, "payload": {}, "status": { "type": "string" }, "attemptCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "responseStatusCode": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "responseBody": { "type": [ "string", "null" ] }, "responseTimeMs": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "errorMessage": { "type": [ "string", "null" ] }, "nextRetryAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "eventType", "eventId", "payload", "status", "attemptCount", "responseStatusCode", "responseBody", "responseTimeMs", "errorMessage", "nextRetryAt", "deliveredAt", "createdAt" ], "additionalProperties": false } }, "pagination": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "offset", "total", "hasMore" ], "additionalProperties": false } }, "required": [ "data", "pagination" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "webhooks.delivery_logs", "x-eightyone-permission": "api_keys:view", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/webhooks/{id}/logs/{logId}/retry": { "post": { "operationId": "webhooks.retry_delivery", "summary": "Retry a delivery", "description": "Re-send one logged delivery of this webhook.\n\nPermission: `webhooks:manage`.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "logId", "in": "path", "required": true, "schema": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "deliveryLogId": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "message", "deliveryLogId" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "webhooks.retry_delivery", "x-eightyone-permission": "webhooks:manage", "x-eightyone-effect": "write", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "unsupported" } }, "/api/v1/webhooks/{id}/test": { "post": { "operationId": "webhooks.test", "summary": "Send a test event", "description": "Queue a test delivery to THIS webhook only: a signed message of type webhook.test, to check your endpoint and its signature verification.\n\nPermission: `webhooks:manage`.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "webhookId": { "type": "string" } }, "required": [ "message", "webhookId" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "webhooks.test", "x-eightyone-permission": "webhooks:manage", "x-eightyone-effect": "write", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "unsupported" } }, "/api/v1/webhooks/events": { "get": { "operationId": "webhooks.event_types", "summary": "List webhook event types", "description": "Every event a webhook can subscribe to, with what triggers it.\n\nPermission: `api_keys:view`.", "tags": [ "Webhooks" ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "eventTypes": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" } }, "required": [ "name", "description" ], "additionalProperties": false } } }, "required": [ "eventTypes" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "webhooks.event_types", "x-eightyone-permission": "api_keys:view", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/work-orders": { "get": { "operationId": "work_orders.list", "summary": "List work orders", "description": "The company's work orders, newest first, optionally by status. Use for ERP pull-sync or to see what production is working on.\n\nPermission: `production:view`.", "tags": [ "Production" ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "draft", "released", "in_progress", "completed", "closed", "cancelled" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Work order external id" }, "code": { "type": "string", "description": "Human code, e.g. WO-1009" }, "externalSystemId": { "description": "Your (ERP) id for the order", "type": [ "string", "null" ] }, "source": { "type": "string", "description": "dashboard or erp" }, "status": { "type": "string", "enum": [ "draft", "released", "in_progress", "completed", "closed", "cancelled" ] }, "product": { "anyOf": [ { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "name": { "type": "string" } }, "required": [ "sku", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "quantity": { "type": "number" }, "uom": { "type": [ "string", "null" ] }, "dueDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "routing": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "name", "version" ], "additionalProperties": false }, { "type": "null" } ] }, "releasedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "code", "externalSystemId", "source", "status", "product", "quantity", "uom", "dueDate", "routing", "releasedAt", "completedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "work_orders.list", "x-eightyone-permission": "production:view", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" }, "post": { "operationId": "work_orders.upsert", "summary": "Create or update a work order (ERP orders in)", "description": "Idempotent on externalSystemId: a new id creates a draft order; re-sending updates it while it is still a draft and is a no-op afterwards. Lands on the product's released routing when there is exactly one. Release it with work_orders.release.\n\nPermission: `production:manage`.", "tags": [ "Production" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "externalSystemId": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Your (ERP) id for the order: the upsert key" }, "productId": { "description": "EightyOne product id (or give productSku)", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "productSku": { "description": "Product SKU (case-insensitive)", "type": "string", "maxLength": 255 }, "quantity": { "type": "number", "minimum": 0 }, "uom": { "type": "string", "maxLength": 32 }, "dueDate": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } ] }, "code": { "description": "Human code; defaults to the next WO-n", "type": "string", "maxLength": 64 } }, "required": [ "externalSystemId" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "workOrder": { "type": "object", "properties": { "id": { "type": "string", "description": "Work order external id" }, "code": { "type": "string", "description": "Human code, e.g. WO-1009" }, "externalSystemId": { "description": "Your (ERP) id for the order", "type": [ "string", "null" ] }, "source": { "type": "string", "description": "dashboard or erp" }, "status": { "type": "string", "enum": [ "draft", "released", "in_progress", "completed", "closed", "cancelled" ] }, "product": { "anyOf": [ { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "name": { "type": "string" } }, "required": [ "sku", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "quantity": { "type": "number" }, "uom": { "type": [ "string", "null" ] }, "dueDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "routing": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "name", "version" ], "additionalProperties": false }, { "type": "null" } ] }, "releasedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "code", "externalSystemId", "source", "status", "product", "quantity", "uom", "dueDate", "routing", "releasedAt", "completedAt", "createdAt", "updatedAt" ], "additionalProperties": false }, "created": { "type": "boolean" } }, "required": [ "workOrder", "created" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "work_orders.upsert", "x-eightyone-permission": "production:manage", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "transactional" } }, "/api/v1/work-orders/{externalId}": { "get": { "operationId": "work_orders.get", "summary": "Get a work order", "description": "One work order with its operations (the traveler's tasks) and their status.\n\nPermission: `production:view`.", "tags": [ "Production" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string", "description": "Work order external id" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Work order external id" }, "code": { "type": "string", "description": "Human code, e.g. WO-1009" }, "externalSystemId": { "description": "Your (ERP) id for the order", "type": [ "string", "null" ] }, "source": { "type": "string", "description": "dashboard or erp" }, "status": { "type": "string", "enum": [ "draft", "released", "in_progress", "completed", "closed", "cancelled" ] }, "product": { "anyOf": [ { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "name": { "type": "string" } }, "required": [ "sku", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "quantity": { "type": "number" }, "uom": { "type": [ "string", "null" ] }, "dueDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "routing": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "name", "version" ], "additionalProperties": false }, { "type": "null" } ] }, "releasedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "operations": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "status": { "type": "string", "description": "open, ready, dispatched, done, …" }, "routingStepId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "title", "status", "routingStepId" ], "additionalProperties": false } } }, "required": [ "id", "code", "externalSystemId", "source", "status", "product", "quantity", "uom", "dueDate", "routing", "releasedAt", "completedAt", "createdAt", "updatedAt", "operations" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "work_orders.get", "x-eightyone-permission": "production:view", "x-eightyone-effect": "read", "x-eightyone-idempotent": false, "x-eightyone-dry-run": "n/a" } }, "/api/v1/work-orders/{externalId}/release": { "post": { "operationId": "work_orders.release", "summary": "Release a work order", "description": "Release a draft work order to the floor: one operation task per routing step, each on the only machine of its work center when there is just one, with the type's parameters pinned and later steps waiting for gates. Needs 'Release work orders'. Preview it with dryRun first: it lists the operations it creates.\n\nPermission: `work_orders:release`.", "tags": [ "Production" ], "parameters": [ { "name": "externalId", "in": "path", "required": true, "schema": { "type": "string", "description": "Work order external id" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Work order external id" }, "code": { "type": "string", "description": "Human code, e.g. WO-1009" }, "externalSystemId": { "description": "Your (ERP) id for the order", "type": [ "string", "null" ] }, "source": { "type": "string", "description": "dashboard or erp" }, "status": { "type": "string", "enum": [ "draft", "released", "in_progress", "completed", "closed", "cancelled" ] }, "product": { "anyOf": [ { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "name": { "type": "string" } }, "required": [ "sku", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "quantity": { "type": "number" }, "uom": { "type": [ "string", "null" ] }, "dueDate": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "routing": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "name", "version" ], "additionalProperties": false }, { "type": "null" } ] }, "releasedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "code", "externalSystemId", "source", "status", "product", "quantity", "uom", "dueDate", "routing", "releasedAt", "completedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "work_orders.release", "x-eightyone-permission": "work_orders:release", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "preview" } }, "/api/v1/work-orders/batch": { "post": { "operationId": "work_orders.batch_upsert", "summary": "Create or update many work orders", "description": "Upsert up to 500 orders; each succeeds or fails on its own (results in input order).\n\nPermission: `production:manage`.", "tags": [ "Production" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: a repeated key returns the first result for 24 h", "schema": { "type": "string", "maxLength": 255 } }, { "name": "Prefer", "in": "header", "required": false, "description": "`dry-run`: validate and return the planned changes without committing", "schema": { "type": "string", "enum": [ "dry-run" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "orders": { "minItems": 1, "maxItems": 500, "type": "array", "items": {}, "description": "Each item is a work_orders.upsert input; an invalid item fails on its own" } }, "required": [ "orders" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "externalSystemId": { "type": "string" }, "ok": { "type": "boolean" }, "created": { "type": "boolean" }, "error": { "type": "string" } }, "required": [ "externalSystemId", "ok" ], "additionalProperties": false } } }, "required": [ "results" ], "additionalProperties": false } } } }, "400": { "description": "Invalid input (problem `invalid_input` lists the fields)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Missing permission (problem `missing_permission`), or the key's company doesn't match", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict (e.g. an Idempotency-Key still in progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable (e.g. `dry_run_unsupported`, `idempotency_key_reused`)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-eightyone-capability": "work_orders.batch_upsert", "x-eightyone-permission": "production:manage", "x-eightyone-effect": "write", "x-eightyone-idempotent": true, "x-eightyone-dry-run": "transactional" } } }, "webhooks": { "task.created": { "post": { "summary": "task.created", "description": "A task was created: by a person, the API, an agent, a flow, a schedule or a work order's release.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "The message id: the same for every retry of this event (de-duplicate on it)", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was sent (reject old ones to stop replays)", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Space-separated \"v1a,\" over \"..\"; verify with a key from /api/v1/webhook-signing-keys", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "timestamp", "data" ], "properties": { "type": { "const": "task.created" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string", "description": "Task external id" }, "title": { "type": "string" }, "status": { "type": "string" }, "priorityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Priority level, as the API uses it" }, "type": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "dueDate": { "anyOf": [ { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "description": "ISO 8601" }, { "type": "null" } ] }, "workOrderId": { "description": "Work order external id, for an operation", "type": [ "string", "null" ] } }, "required": [ "id", "title", "status", "priorityId", "type", "dueDate", "workOrderId" ], "additionalProperties": false }, "ssu": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "SSU external id" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "task", "ssu" ], "additionalProperties": false } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried, up to 6 attempts over a day." } } } }, "task.status_changed": { "post": { "summary": "task.status_changed", "description": "A task moved to another status (open, preparation, ready, dispatched, submitted, done, incomplete, declined).", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "The message id: the same for every retry of this event (de-duplicate on it)", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was sent (reject old ones to stop replays)", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Space-separated \"v1a,\" over \"..\"; verify with a key from /api/v1/webhook-signing-keys", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "timestamp", "data" ], "properties": { "type": { "const": "task.status_changed" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "task": { "type": "object", "properties": { "id": { "type": "string", "description": "Task external id" }, "title": { "type": "string" }, "status": { "type": "string" }, "priorityId": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Priority level, as the API uses it" }, "type": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "dueDate": { "anyOf": [ { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "description": "ISO 8601" }, { "type": "null" } ] }, "workOrderId": { "description": "Work order external id, for an operation", "type": [ "string", "null" ] } }, "required": [ "id", "title", "status", "priorityId", "type", "dueDate", "workOrderId" ], "additionalProperties": false }, "ssu": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "SSU external id" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "previousStatus": { "type": [ "string", "null" ] }, "status": { "type": "string" } }, "required": [ "task", "ssu", "previousStatus", "status" ], "additionalProperties": false } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried, up to 6 attempts over a day." } } } }, "client.created": { "post": { "summary": "client.created", "description": "A client was created.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "The message id: the same for every retry of this event (de-duplicate on it)", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was sent (reject old ones to stop replays)", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Space-separated \"v1a,\" over \"..\"; verify with a key from /api/v1/webhook-signing-keys", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "timestamp", "data" ], "properties": { "type": { "const": "client.created" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "client": { "type": "object", "properties": { "id": { "description": "Your id for the client (its external system id)", "type": [ "string", "null" ] }, "name": { "type": "string" }, "isActive": { "type": "boolean" }, "contactPersonName": { "type": [ "string", "null" ] }, "contactPersonEmail": { "type": [ "string", "null" ] }, "contactPersonPhone": { "type": [ "string", "null" ] }, "color": { "type": [ "string", "null" ] }, "createdAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "description": "ISO 8601" } }, "required": [ "id", "name", "isActive", "contactPersonName", "contactPersonEmail", "contactPersonPhone", "color", "createdAt" ], "additionalProperties": false } }, "required": [ "client" ], "additionalProperties": false } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried, up to 6 attempts over a day." } } } }, "work_order.released": { "post": { "summary": "work_order.released", "description": "A work order went to the floor: its operations were created.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "The message id: the same for every retry of this event (de-duplicate on it)", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was sent (reject old ones to stop replays)", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Space-separated \"v1a,\" over \"..\"; verify with a key from /api/v1/webhook-signing-keys", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "timestamp", "data" ], "properties": { "type": { "const": "work_order.released" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "workOrder": { "type": "object", "properties": { "id": { "type": "string", "description": "Work order external id" }, "code": { "type": [ "string", "null" ] }, "product": { "anyOf": [ { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "name": { "type": "string" } }, "required": [ "sku", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "quantity": { "type": "number" }, "dueDate": { "anyOf": [ { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "description": "ISO 8601" }, { "type": "null" } ] } }, "required": [ "id", "code", "product", "quantity", "dueDate" ], "additionalProperties": false }, "operations": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "How many operation tasks the release created" } }, "required": [ "workOrder", "operations" ], "additionalProperties": false } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried, up to 6 attempts over a day." } } } }, "work_order.completed": { "post": { "summary": "work_order.completed", "description": "A work order's last operation was done.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "The message id: the same for every retry of this event (de-duplicate on it)", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was sent (reject old ones to stop replays)", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Space-separated \"v1a,\" over \"..\"; verify with a key from /api/v1/webhook-signing-keys", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "timestamp", "data" ], "properties": { "type": { "const": "work_order.completed" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "workOrder": { "type": "object", "properties": { "id": { "type": "string", "description": "Work order external id" }, "code": { "type": [ "string", "null" ] }, "product": { "anyOf": [ { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "name": { "type": "string" } }, "required": [ "sku", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "quantity": { "type": "number" }, "completedAt": { "anyOf": [ { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "description": "ISO 8601" }, { "type": "null" } ] } }, "required": [ "id", "code", "product", "quantity", "completedAt" ], "additionalProperties": false } }, "required": [ "workOrder" ], "additionalProperties": false } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried, up to 6 attempts over a day." } } } }, "downtime.started": { "post": { "summary": "downtime.started", "description": "A machine stopped: detected from telemetry (auto) or reported by a person (manual).", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "The message id: the same for every retry of this event (de-duplicate on it)", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was sent (reject old ones to stop replays)", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Space-separated \"v1a,\" over \"..\"; verify with a key from /api/v1/webhook-signing-keys", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "timestamp", "data" ], "properties": { "type": { "const": "downtime.started" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "downtime": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Downtime event id, as downtime_events.list shows it" }, "ssu": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "SSU external id" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "source": { "type": "string", "enum": [ "auto", "manual" ] }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "description": "ISO 8601" }, "endedAt": { "anyOf": [ { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "description": "ISO 8601" }, { "type": "null" } ] }, "durationSeconds": { "type": [ "number", "null" ] } }, "required": [ "id", "ssu", "source", "startedAt", "endedAt", "durationSeconds" ], "additionalProperties": false } }, "required": [ "downtime" ], "additionalProperties": false } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried, up to 6 attempts over a day." } } } }, "downtime.ended": { "post": { "summary": "downtime.ended", "description": "A machine stoppage ended.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "The message id: the same for every retry of this event (de-duplicate on it)", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was sent (reject old ones to stop replays)", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Space-separated \"v1a,\" over \"..\"; verify with a key from /api/v1/webhook-signing-keys", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "timestamp", "data" ], "properties": { "type": { "const": "downtime.ended" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "downtime": { "type": "object", "properties": { "id": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Downtime event id, as downtime_events.list shows it" }, "ssu": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "SSU external id" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "source": { "type": "string", "enum": [ "auto", "manual" ] }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "description": "ISO 8601" }, "endedAt": { "anyOf": [ { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "string" } ], "description": "ISO 8601" }, { "type": "null" } ] }, "durationSeconds": { "type": [ "number", "null" ] } }, "required": [ "id", "ssu", "source", "startedAt", "endedAt", "durationSeconds" ], "additionalProperties": false } }, "required": [ "downtime" ], "additionalProperties": false } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried, up to 6 attempts over a day." } } } }, "lot.created": { "post": { "summary": "lot.created", "description": "A lot was created: received from a vendor, produced by a work order, or entered by hand.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "The message id: the same for every retry of this event (de-duplicate on it)", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was sent (reject old ones to stop replays)", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Space-separated \"v1a,\" over \"..\"; verify with a key from /api/v1/webhook-signing-keys", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "timestamp", "data" ], "properties": { "type": { "const": "lot.created" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "lot": { "type": "object", "properties": { "code": { "type": "string" }, "product": { "anyOf": [ { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "name": { "type": "string" } }, "required": [ "sku", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "status": { "type": "string" }, "workOrderId": { "description": "The work order that produced it", "type": [ "string", "null" ] }, "vendor": { "description": "The vendor it came from", "type": [ "string", "null" ] } }, "required": [ "code", "product", "status", "workOrderId", "vendor" ], "additionalProperties": false } }, "required": [ "lot" ], "additionalProperties": false } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried, up to 6 attempts over a day." } } } }, "stock.reorder_triggered": { "post": { "summary": "stock.reorder_triggered", "description": "A product's stock fell to its reorder point (lead time × measured consumption). Sent once per crossing; it re-arms when stock recovers.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "The message id: the same for every retry of this event (de-duplicate on it)", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was sent (reject old ones to stop replays)", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Space-separated \"v1a,\" over \"..\"; verify with a key from /api/v1/webhook-signing-keys", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "timestamp", "data" ], "properties": { "type": { "const": "stock.reorder_triggered" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "product": { "anyOf": [ { "type": "object", "properties": { "sku": { "type": [ "string", "null" ] }, "name": { "type": "string" } }, "required": [ "sku", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "onHand": { "type": "number" }, "reorderPoint": { "type": "number" }, "dailyConsumption": { "type": "number" }, "leadTimeDays": { "type": "number" }, "suggestedQuantity": { "type": "number" }, "storageSiteId": { "description": "Storage site external id, when the policy is per site", "type": [ "string", "null" ] } }, "required": [ "product", "onHand", "reorderPoint", "dailyConsumption", "leadTimeDays", "suggestedQuantity", "storageSiteId" ], "additionalProperties": false } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried, up to 6 attempts over a day." } } } }, "handoff.received": { "post": { "summary": "handoff.received", "description": "A partner company sent you a task.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "The message id: the same for every retry of this event (de-duplicate on it)", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was sent (reject old ones to stop replays)", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Space-separated \"v1a,\" over \"..\"; verify with a key from /api/v1/webhook-signing-keys", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "timestamp", "data" ], "properties": { "type": { "const": "handoff.received" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "handoff": { "type": "object", "properties": { "id": { "type": "string" }, "direction": { "type": "string" }, "state": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "direction", "state", "status" ], "additionalProperties": {} } }, "required": [ "handoff" ], "additionalProperties": false } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried, up to 6 attempts over a day." } } } }, "handoff.status_changed": { "post": { "summary": "handoff.status_changed", "description": "A task handed between partner companies changed status (sent to both sides).", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "The message id: the same for every retry of this event (de-duplicate on it)", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was sent (reject old ones to stop replays)", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Space-separated \"v1a,\" over \"..\"; verify with a key from /api/v1/webhook-signing-keys", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "timestamp", "data" ], "properties": { "type": { "const": "handoff.status_changed" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "handoff": { "type": "object", "properties": { "id": { "type": "string" }, "direction": { "type": "string" }, "state": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "direction", "state", "status" ], "additionalProperties": {} } }, "required": [ "handoff" ], "additionalProperties": false } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried, up to 6 attempts over a day." } } } }, "handoff.declined": { "post": { "summary": "handoff.declined", "description": "A handed-over task was declined (sent to both sides).", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "The message id: the same for every retry of this event (de-duplicate on it)", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was sent (reject old ones to stop replays)", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Space-separated \"v1a,\" over \"..\"; verify with a key from /api/v1/webhook-signing-keys", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "timestamp", "data" ], "properties": { "type": { "const": "handoff.declined" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "handoff": { "type": "object", "properties": { "id": { "type": "string" }, "direction": { "type": "string" }, "state": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "direction", "state", "status" ], "additionalProperties": {} } }, "required": [ "handoff" ], "additionalProperties": false } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried, up to 6 attempts over a day." } } } }, "handoff.deleted": { "post": { "summary": "handoff.deleted", "description": "A handoff was withdrawn or deleted (sent to both sides).", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "The message id: the same for every retry of this event (de-duplicate on it)", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was sent (reject old ones to stop replays)", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Space-separated \"v1a,\" over \"..\"; verify with a key from /api/v1/webhook-signing-keys", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "timestamp", "data" ], "properties": { "type": { "const": "handoff.deleted" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "handoff": { "type": "object", "properties": { "id": { "type": "string" }, "direction": { "type": "string" }, "state": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "direction", "state", "status" ], "additionalProperties": {} } }, "required": [ "handoff" ], "additionalProperties": false } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried, up to 6 attempts over a day." } } } }, "partner_delivery.incoming": { "post": { "summary": "partner_delivery.incoming", "description": "A partner company sent you goods: they are in transit to you.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "The message id: the same for every retry of this event (de-duplicate on it)", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was sent (reject old ones to stop replays)", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Space-separated \"v1a,\" over \"..\"; verify with a key from /api/v1/webhook-signing-keys", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "timestamp", "data" ], "properties": { "type": { "const": "partner_delivery.incoming" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "delivery": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "direction": { "type": "string" }, "state": { "type": "string" } }, "required": [ "id", "kind", "direction", "state" ], "additionalProperties": {} } }, "required": [ "delivery" ], "additionalProperties": false } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried, up to 6 attempts over a day." } } } }, "partner_delivery.received": { "post": { "summary": "partner_delivery.received", "description": "A partner received goods you sent.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "The message id: the same for every retry of this event (de-duplicate on it)", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was sent (reject old ones to stop replays)", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Space-separated \"v1a,\" over \"..\"; verify with a key from /api/v1/webhook-signing-keys", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "timestamp", "data" ], "properties": { "type": { "const": "partner_delivery.received" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "delivery": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "direction": { "type": "string" }, "state": { "type": "string" } }, "required": [ "id", "kind", "direction", "state" ], "additionalProperties": {} } }, "required": [ "delivery" ], "additionalProperties": false } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried, up to 6 attempts over a day." } } } }, "partner_delivery.shortfall": { "post": { "summary": "partner_delivery.shortfall", "description": "A partner reported goods you sent as missing or damaged.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "The message id: the same for every retry of this event (de-duplicate on it)", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was sent (reject old ones to stop replays)", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Space-separated \"v1a,\" over \"..\"; verify with a key from /api/v1/webhook-signing-keys", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "timestamp", "data" ], "properties": { "type": { "const": "partner_delivery.shortfall" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "delivery": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "direction": { "type": "string" }, "state": { "type": "string" } }, "required": [ "id", "kind", "direction", "state" ], "additionalProperties": {} } }, "required": [ "delivery" ], "additionalProperties": false } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried, up to 6 attempts over a day." } } } }, "data_package.received": { "post": { "summary": "data_package.received", "description": "A partner released the data package you requested.", "parameters": [ { "name": "webhook-id", "in": "header", "required": true, "description": "The message id: the same for every retry of this event (de-duplicate on it)", "schema": { "type": "string" } }, { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Unix seconds when this attempt was sent (reject old ones to stop replays)", "schema": { "type": "string" } }, { "name": "webhook-signature", "in": "header", "required": true, "description": "Space-separated \"v1a,\" over \"..\"; verify with a key from /api/v1/webhook-signing-keys", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "timestamp", "data" ], "properties": { "type": { "const": "data_package.received" }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "dataPackage": { "type": "object", "properties": { "id": { "type": "string" }, "dataRequestId": { "type": "string" }, "from": { "type": "object", "properties": { "name": { "type": "string" }, "shortName": { "type": "string" } }, "required": [ "name", "shortName" ], "additionalProperties": false } }, "required": [ "id", "dataRequestId", "from" ], "additionalProperties": false } }, "required": [ "dataPackage" ], "additionalProperties": false } } } } } }, "responses": { "2XX": { "description": "Received. Anything else is retried, up to 6 attempts over a day." } } } } } }