{ "openapi": "3.1.0", "info": { "title": "Deconfound Flavor Lab API", "version": "2.22.0", "description": "Create recipes, obtain quotes, submit customer service orders and retrieve recorded reports. Authenticate machine requests with X-Deconfound-Api-Key; browser sessions use Supabase. Native MCP at /mcp accepts the same scoped X-Deconfound-Api-Key; clients must support custom headers. Payment mode test uses an internal simulator; stripe_test uses hosted Stripe sandbox Checkout and verified server-side reconciliation. Neither captures real funds. Advanced lab-orders are separate private bench records." }, "servers": [ { "url": "https://labs.deconfound.com/api/v2" } ], "security": [ { "DeconfoundKey": [] } ], "paths": { "/requests": { "get": { "operationId": "listRequests", "summary": "List your shared requests", "description": "Required scope: orders:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RequestSubmission" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "submitRequest", "summary": "Share a request with Deconfound after explicit consent; no kitchen fulfillment", "description": "Required scope: orders:write. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. Structured experiments use the /experiments quote and submission routes. Legacy prompt, generation, idea and order sources remain available. Without orders:read, successful creation and identical replay return {request:{id,createdAt,links:{self}},receiptOnly:true}. The receipt does not grant read access. With orders:read, the full authorized resource is returned. Referencing a saved idea or website generation requires ideas:read in addition to the operation scopes; referencing a saved order requires orders:read. Source scopes are checked before retrieval and idempotent replay. Fully supplied ingredient/prompt inputs do not require ideas:read. An owned guest-browser generation is accessible only through that guest session capability, not through an API-key exception.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[-a-zA-Z0-9_.:]{8,128}$" }, "description": "Unique per workspace and operation. Reuse with exactly the same normalized request after network failures. No automatic expiration in v2." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitRequest" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "request": { "$ref": "#/components/schemas/RequestSubmission" } }, "required": [ "request" ] }, { "type": "object", "properties": { "request": { "$ref": "#/components/schemas/CreationReceipt" }, "receiptOnly": { "const": true } }, "required": [ "request", "receiptOnly" ] } ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/requests/{id}": { "post": { "operationId": "withdrawRequest", "summary": "Withdraw and redact your shared request; use status withdrawn", "description": "Required scope: orders:read and orders:write. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestStatus" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "$ref": "#/components/schemas/RequestSubmission" } }, "required": [ "request" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/inbox": { "get": { "operationId": "listInbox", "summary": "Operator-only incoming shared requests", "description": "Required scope: lab:write. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RequestSubmission" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/inbox/{id}": { "post": { "operationId": "reviewRequest", "summary": "Mark a submission reviewed or closed; operator only", "description": "Required scope: lab:write. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestStatus" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "$ref": "#/components/schemas/RequestSubmission" } }, "required": [ "request" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trials": { "get": { "operationId": "listTrials", "summary": "List saved comparison briefs", "description": "Required scope: orders:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TrialSummary" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createTrial", "summary": "Save a brief and decision question", "description": "Required scope: orders:write. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. Without orders:read, successful creation and identical replay return {trial:{id,createdAt,links:{self}},receiptOnly:true}. The receipt does not grant read access. With orders:read, the full authorized resource is returned.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[-a-zA-Z0-9_.:]{8,128}$" }, "description": "Unique per workspace and operation. Reuse with exactly the same normalized request after network failures. No automatic expiration in v2." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTrial" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "trial": { "$ref": "#/components/schemas/Trial" } }, "required": [ "trial" ] }, { "type": "object", "properties": { "trial": { "$ref": "#/components/schemas/CreationReceipt" }, "receiptOnly": { "const": true } }, "required": [ "trial", "receiptOnly" ] } ] } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "trial": { "$ref": "#/components/schemas/Trial" } }, "required": [ "trial" ] }, { "type": "object", "properties": { "trial": { "$ref": "#/components/schemas/CreationReceipt" }, "receiptOnly": { "const": true } }, "required": [ "trial", "receiptOnly" ] } ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trials/{id}": { "get": { "operationId": "getTrial", "summary": "Read trial state and observation history", "description": "Required scope: orders:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "trial": { "$ref": "#/components/schemas/Trial" } }, "required": [ "trial" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trials/{id}/report": { "get": { "operationId": "getTrialReport", "summary": "Read exact orders, evidence and descriptive paired summaries", "description": "Required scope: orders:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrialReport" } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trials/{id}/actions": { "post": { "operationId": "updateTrial", "summary": "Link an order, record a tasting, or select a direction", "description": "Required scope: orders:read and orders:write for link_order/select; lab:write for record_tasting. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. Every command needs current trial revision. Maximum three candidates and one reference. Design locks after tasting. New observations require assembled reviewed batches and two candidates; corrections retain history. /trial-api.html documents codes, limits and recovery.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[-a-zA-Z0-9_.:]{8,128}$" }, "description": "Unique per workspace and operation. Reuse with exactly the same normalized request after network failures. No automatic expiration in v2." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrialAction" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "trial": { "$ref": "#/components/schemas/Trial" } }, "required": [ "trial" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/processes": { "get": { "operationId": "listProcesses", "summary": "Get process capabilities and qualification requirements", "description": "Required scope: ingredients:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "processLibraryVersion": { "type": "string" }, "processes": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "scope": { "$ref": "#/components/schemas/LabScope" } }, "required": [ "processLibraryVersion", "processes", "scope" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lab-orders/{id}/worksheet": { "get": { "operationId": "getWorksheet", "summary": "Get the frozen bench plan, readiness holds and next step per batch", "description": "Required scope: orders:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorksheetView" } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lab-orders/{id}/steps": { "post": { "operationId": "recordAssemblyStep", "summary": "Record the next physical assembly step or a clerical correction", "description": "Required scope: lab:write. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[-a-zA-Z0-9_.:]{8,128}$" }, "description": "Unique per workspace and operation. Reuse with exactly the same normalized request after network failures. No automatic expiration in v2." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordStep" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/LabOrder" } }, "required": [ "order" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ingredients": { "get": { "operationId": "searchIngredients", "summary": "Search the ingredient bank", "description": "Required scope: ingredients:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "bank", "in": "query", "schema": { "enum": [ "launch", "extended", "review" ] }, "description": "Omit to search all records. Launch is the current preferred ingredient bank, not physical inventory." }, { "name": "q", "in": "query", "schema": { "type": "string", "maxLength": 300 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 500 } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "catalogVersion": { "type": "string" }, "checkedAt": { "type": "string" }, "ingredients": { "type": "array", "items": { "$ref": "#/components/schemas/Ingredient" } }, "launchBank": { "$ref": "#/components/schemas/LaunchBank" }, "scope": { "$ref": "#/components/schemas/LabScope" }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/Metric" } } }, "required": [ "catalogVersion", "checkedAt", "ingredients", "launchBank", "scope", "metrics" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ingredients/{ingredientId}": { "get": { "operationId": "getIngredient", "summary": "Read a basic ingredient profile and functional details", "description": "Required scope: ingredients:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "ingredientId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "catalogVersion": { "type": "string" }, "ingredient": { "$ref": "#/components/schemas/Ingredient" } }, "required": [ "catalogVersion", "ingredient" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ideas": { "get": { "operationId": "listIdeas", "summary": "List ideas in this workspace", "description": "Required scope: ideas:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Idea" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createIdea", "summary": "Request an AI recipe, optionally constrained to selected ingredients", "description": "Required scope: ideas:write. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. Optional ingredientSelection.availableIds permits 1–20 unique known non-water IDs; requiredIds (0–8) must be a subset and must appear in any executable recipe. Candidates awaiting sourcing or dose qualification cannot enter quantified recipes. If essential inputs are missing, recipes is empty with a concise reason. Optional variants contains 1–6 unique {id,prompt} objects; each shares the global request constraints and may produce a complete candidate or a separate gap. Omit selection to consider the full catalog. includeJuices defaults to true for beverages, consistent with Studio; explicit false prohibits juice. Flavor evaluations always disable juice. Arrays normalize as sets. The server snapshots catalogVersion and blocks new generation if it changes. Selection does not assert physical stock. Without ideas:read, successful creation and identical replay return {idea:{id,createdAt,links:{self}},receiptOnly:true}. The receipt does not grant read access. With ideas:read, the full authorized resource is returned.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[-a-zA-Z0-9_.:]{8,128}$" }, "description": "Unique per workspace and operation. Reuse with exactly the same normalized request after network failures. No automatic expiration in v2." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateIdea" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "idea": { "$ref": "#/components/schemas/Idea" } }, "required": [ "idea" ] }, { "type": "object", "properties": { "idea": { "$ref": "#/components/schemas/CreationReceipt" }, "receiptOnly": { "const": true } }, "required": [ "idea", "receiptOnly" ] } ] } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "idea": { "$ref": "#/components/schemas/Idea" } }, "required": [ "idea" ] }, { "type": "object", "properties": { "idea": { "$ref": "#/components/schemas/CreationReceipt" }, "receiptOnly": { "const": true } }, "required": [ "idea", "receiptOnly" ] } ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ideas/{id}": { "get": { "operationId": "getIdea", "summary": "Read progress or retrieve a saved result", "description": "Required scope: ideas:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "idea": { "$ref": "#/components/schemas/Idea" } }, "required": [ "idea" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ideas/{id}/generate": { "post": { "operationId": "generateIdea", "summary": "Run two AI passes and save the result", "description": "Required scope: ideas:read and ideas:write. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. Foreground request; configure a client timeout of 300 seconds. The 240-second lease bounds interrupted attempts. Unsupported ideas are successful results with fulfillment.status=unsupported and alternatives. Show the proposed changes before creating a new idea with the complete alternative.request. An alternative is a new brief, not an executable recipe or an order. If action=edit, ask the user to revise the stated constraint before resubmitting.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[-a-zA-Z0-9_.:]{8,128}$" }, "description": "Unique per workspace and operation. Reuse with exactly the same normalized request after network failures. No automatic expiration in v2." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Revision" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "idea": { "$ref": "#/components/schemas/Idea" } }, "required": [ "idea" ] } } } }, "202": { "description": "Replay of a still-running attempt. Read the idea; see Retry-After. This endpoint does not schedule a background job.", "content": { "application/json": { "schema": { "type": "object", "properties": { "idea": { "$ref": "#/components/schemas/Idea" } }, "required": [ "idea" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lab-orders": { "get": { "operationId": "listLabOrders", "summary": "List lab work orders", "description": "Required scope: orders:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LabOrder" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createLabOrder", "summary": "Freeze a formula and ingredients as a pending lab work order", "description": "Required scope: orders:write. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. Accepts saved idea, authentic Studio generation ID, or explicit ingredients. Default tests record actual batch mass with null limits; explicitly requested instrument tests require a reviewed custom quote; null is measurement-only, never a passing target. No-recipe results cannot create orders. Optional variantId selects a complete variant; omitted uses the first complete candidate. New bench orders require configure, accept, start, sequential step evidence and measurements. Ingredient IDs select catalog profiles. Grams represent the ingredient including its carrier, not pure flavor molecules. Direct ingredient orders accept optional base.water with sourceMassG. If present, all ingredients must total batchMassG exactly or return 422 BATCH_MASS_MISMATCH (details: batchMassG, ingredientMassG, differenceG = total minus target). No automatic adjustment occurs. Omit water to calculate the remainder. Use 1–20 non-water ingredients plus optional water; explicit CO2 is not allowed. No purchasing or external dispatch is connected. Direct ingredient orders optionally accept preparation and benchSettings in the same request. Exact recipe amounts are never rewritten by AI. Settings are proposals until lab approval. Custom methods replace the automatic middle of the worksheet while retaining setup, evidence and finish. Explicit out-of-scope production instructions return OUTSIDE_LAB_SCOPE; other text remains subject to operator method review, not comprehensive semantic certification. New orders include a provisional TestQuote or quote_required with a null total. Operator configuration preserves the original estimate and marks pricingReviewRequired; prior prices cannot be treated as current for expanded scope. Without orders:read, successful creation and identical replay return {order:{id,createdAt,links:{self}},receiptOnly:true}. The receipt does not grant read access. With orders:read, the full authorized resource is returned. Referencing a saved idea or website generation requires ideas:read in addition to the operation scopes; referencing a saved order requires orders:read. Source scopes are checked before retrieval and idempotent replay. Fully supplied ingredient/prompt inputs do not require ideas:read. An owned guest-browser generation is accessible only through that guest session capability, not through an API-key exception.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[-a-zA-Z0-9_.:]{8,128}$" }, "description": "Unique per workspace and operation. Reuse with exactly the same normalized request after network failures. No automatic expiration in v2." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLabOrder" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/LabOrder" } }, "required": [ "order" ] }, { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/CreationReceipt" }, "receiptOnly": { "const": true } }, "required": [ "order", "receiptOnly" ] } ] } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/LabOrder" } }, "required": [ "order" ] }, { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/CreationReceipt" }, "receiptOnly": { "const": true } }, "required": [ "order", "receiptOnly" ] } ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lab-orders/{id}": { "get": { "operationId": "getLabOrder", "summary": "Get an order with its frozen recipe and basic ingredient information", "description": "Required scope: orders:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/LabOrder" } }, "required": [ "order" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lab-orders/{id}/actions": { "post": { "operationId": "transitionLabOrder", "summary": "Configure, accept, start, cancel or abort a lab work order", "description": "Required scope: orders:read and orders:write for cancel; lab:write for configure, accept, start and abort. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[-a-zA-Z0-9_.:]{8,128}$" }, "description": "Unique per workspace and operation. Reuse with exactly the same normalized request after network failures. No automatic expiration in v2." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderAction" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/LabOrder" } }, "required": [ "order" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lab-orders/{id}/results": { "get": { "operationId": "getLabResults", "summary": "Get partial or complete measured results", "description": "Required scope: orders:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "revision": { "type": "integer" }, "results": { "$ref": "#/components/schemas/Evaluation" } }, "required": [ "orderId", "status", "revision", "results" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "recordLabResults", "summary": "Append recorded evidence or correct an existing entry", "description": "Required scope: lab:write. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[-a-zA-Z0-9_.:]{8,128}$" }, "description": "Unique per workspace and operation. Reuse with exactly the same normalized request after network failures. No automatic expiration in v2." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordResults" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/LabOrder" }, "results": { "$ref": "#/components/schemas/Evaluation" } }, "required": [ "order", "results" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/experiments/capabilities": { "get": { "operationId": "experimentCapabilities", "summary": "Read actual experiment capabilities and limitations", "description": "Required scope: orders:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/experiments/quote": { "post": { "operationId": "quoteExperiment", "summary": "Validate an unpriced planning scope without creating an order", "description": "Required scope: orders:write. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. Referencing a parentRequest also requires orders:read, including replay.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteExperiment" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "const": "planned" }, "plan": { "$ref": "#/components/schemas/ExperimentPlan" }, "quote": { "$ref": "#/components/schemas/ExperimentQuote" }, "notice": { "type": "string" } }, "required": [ "state", "plan", "quote", "notice" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/experiments": { "get": { "operationId": "listExperiments", "summary": "List owned experiment planning summaries; retrieve each resource for evidence state", "description": "Required scope: orders:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "submitExperiment", "summary": "Save an unpriced experiment plan; no order, dispatch or payment", "description": "Required scope: orders:write. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. First POST /experiments/quote. Submit its scopeHash as quoteHash with the identical normalized plan. A changed plan or hash returns 409 QUOTE_CHANGED. Same-key replay recovers the saved plan and current result projection. All free-text plans are unpriced: totalCents is null and no operator quote or confirmation is promised. Never infer a price from plan descriptions. Generate a catalog-backed recipe and use /order-quotes and /orders to purchase supported work. Historical estimate amounts remain stored privately; public reads project an unpriced plan. Planning submissions do not start an order, payment or physical test. Parent requests must be owned, current-revision and not withdrawn. Shared per-day planning intake quotas apply. Without orders:read, successful creation and identical replay return {experiment:{id,createdAt,links:{self}},receiptOnly:true}. The receipt does not grant read access. With orders:read, the full authorized resource is returned. Referencing a parentRequest also requires orders:read, including replay.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[-a-zA-Z0-9_.:]{8,128}$" }, "description": "Unique per workspace and operation. Reuse with exactly the same normalized request after network failures. No automatic expiration in v2." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateExperiment" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "experiment": { "$ref": "#/components/schemas/Experiment" } }, "required": [ "experiment" ] }, { "type": "object", "properties": { "experiment": { "$ref": "#/components/schemas/CreationReceipt" }, "receiptOnly": { "const": true } }, "required": [ "experiment", "receiptOnly" ] } ] } } } }, "201": { "description": "Planning brief saved. No order or lab work started.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "experiment": { "$ref": "#/components/schemas/Experiment" } }, "required": [ "experiment" ] }, { "type": "object", "properties": { "experiment": { "$ref": "#/components/schemas/CreationReceipt" }, "receiptOnly": { "const": true } }, "required": [ "experiment", "receiptOnly" ] } ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/experiments/{id}": { "get": { "operationId": "getExperiment", "summary": "Read an owned experiment, quote and evidence-derived state", "description": "Required scope: orders:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "experiment": { "$ref": "#/components/schemas/Experiment" } }, "required": [ "experiment" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/experiments/{id}/quote": { "get": { "operationId": "getExperimentQuote", "summary": "Read the unpriced planning scope", "description": "Required scope: orders:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "experimentId": { "type": "string", "format": "uuid" }, "quote": { "anyOf": [ { "$ref": "#/components/schemas/ExperimentQuote" }, { "type": "null" } ] } }, "required": [ "experimentId", "quote" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/experiments/{id}/status": { "get": { "operationId": "getExperimentStatus", "summary": "Read review and evidence state separately", "description": "Required scope: orders:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "experimentId": { "type": "string", "format": "uuid" }, "revision": { "type": "integer" }, "state": { "enum": [ "planned", "in_progress", "completed", "closed", "withdrawn" ] }, "reviewStatus": { "type": "string" }, "resultsStatus": { "type": "string" }, "links": { "type": "object" } }, "required": [ "experimentId", "revision", "state", "reviewStatus", "resultsStatus", "links" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/experiments/{id}/results": { "get": { "operationId": "getExperimentResults", "summary": "Read only actual linked owned lab evidence; missing readings remain empty", "description": "Required scope: orders:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "experimentId": { "type": "string", "format": "uuid" }, "state": { "enum": [ "planned", "in_progress", "completed", "closed", "withdrawn" ] }, "results": { "$ref": "#/components/schemas/ExperimentResults" } }, "required": [ "experimentId", "state", "results" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/experiments/{id}/evidence": { "post": { "operationId": "linkExperimentEvidence", "summary": "Operator-only link of an owned batch to an owned experiment; does not perform work", "description": "Required scope: lab:write. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. Existing lab:write and ownership of BOTH request and lab order are required; operators gain no cross-account access. Provide current request and order revisions. Each planned preparation and actual batch may be linked once. Independent repeats require the referenced formulation linked first and identical frozen formula hashes. The order must include all requested metrics, a recorded start, qualification and a currently reviewed bench worksheet. The link pins formula and worksheet hashes; changed scope is flagged and cannot establish completion. Links store references; source lab records remain authoritative and corrections are reflected on GET. Review/closed states cannot fabricate completion. Completion requires reviewed worksheet steps, preparation records, requested measurements and completed source orders. No new evidence, external URL, photo or payment may be submitted here.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[-a-zA-Z0-9_.:]{8,128}$" }, "description": "Unique per workspace and operation. Reuse with exactly the same normalized request after network failures. No automatic expiration in v2." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkExperimentEvidence" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "experiment": { "$ref": "#/components/schemas/Experiment" } }, "required": [ "experiment" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/checkout/quote": { "post": { "operationId": "quoteRecipeTest", "summary": "Retired customer checkout: use /order-quotes", "deprecated": true, "description": "Returns 410 USE_SERVICE_ORDERS. Quote a supported catalog recipe through /order-quotes, then explicitly accept it and begin checkout through /orders. No order is created by this retired endpoint.", "responses": { "410": { "description": "USE_SERVICE_ORDERS: follow /order-quotes and /orders.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/checkout": { "post": { "operationId": "checkoutRecipeTest", "summary": "Retired customer checkout: use /orders", "deprecated": true, "description": "Returns 410 USE_SERVICE_ORDERS. Quote a supported catalog recipe through /order-quotes, then explicitly accept it and begin checkout through /orders. No order is created by this retired endpoint.", "responses": { "410": { "description": "USE_SERVICE_ORDERS: follow /order-quotes and /orders.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/checkout/{id}": { "get": { "operationId": "getCheckout", "summary": "Read a historical receipt; new orders use /orders", "description": "Required scope: orders:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutReceipt" } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/order-quotes": { "post": { "operationId": "quoteOrder", "summary": "Quote a kitchen trial with a sample-condition lab report and optional cool-packed shipping estimate", "description": "Required scope: orders:read (also ideas:read for idea sources). Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. Referencing a saved idea or website generation requires ideas:read in addition to the operation scopes; referencing a saved order requires orders:read. Source scopes are checked before retrieval and idempotent replay. Fully supplied ingredient/prompt inputs do not require ideas:read. An owned guest-browser generation is accessible only through that guest session capability, not through an API-key exception.", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteOrder" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceOffer" } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders": { "post": { "operationId": "placeOrder", "summary": "Create an order and optionally initialize checkout at its accepted saved quote; no charge or physical work begins", "description": "Required scope: orders:read and orders:write. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. Obtain /order-quotes first. quoteHash binds the exact recipe, method, variations, source revision, services, shipping policy and destination. On 409 QUOTE_CHANGED show a fresh quote before retrying. Same-key replay returns the existing frozen order, including withdrawal. Shipping requires a destination; the full shippingAddress is optional until dispatch is approved. The bundled lab report describes sample condition and characteristics (color, clarity, separation and texture), with labeled photos, weighed recipe and maker aroma/flavor notes when performed. packageTotalCents is the trial price. When shipping.status is estimated, totalCents includes its planning estimate; identify this as an estimate, not a carrier quote. The $99-$209 distance-based planning allowance from San Francisco origin ZIP 94133 covers one cool-packed overnight parcel with up to 100 g per recipe version, at most three / 300 g total, subject to actual yield and lab approval. It does not promise full-batch shipment. Only recognized ZIPs in the contiguous U.S. and D.C., with a matching supplied state, receive an estimate. Shipping.destination returns the canonical ZIP, city and state. Distance uses bundled GeoNames postal centroids; this is neither a carrier quote nor an address or service-availability check. The quote hash binds origin, distance tiers and dataset version. Unknown ZIPs, mismatched states and other destinations retain null shipping and full totals with a known package subtotal. Display reviewNotes alongside the price; reasons describe unpriced scope. Overnight refers to transit after approved dispatch, not time from order. No arrival time, sample temperature, instrument reading, payment or dispatch is guaranteed or performed by this request. API-key requests must supply contactEmail. Authenticated same-origin browser requests may omit contactEmail; the verified account email is used and any supplied contactEmail is ignored for new orders. Guest browser sessions receive 401 AUTHENTICATION_REQUIRED from POST /orders, while they can still quote their own generated recipes. Login and the existing same-origin guest-claim flow transfer the recipe into the account before ordering; orders and reports remain owner-scoped. Existing receipts retain their saved contact details on replay. Unsupported or null-priced service requests cannot be submitted. Supported orders proceed directly to checkout without lab confirmation. With checkout:{acceptQuote:true}, first display the exact recipe, services, complete total and current trial terms from /order-api.md, then obtain customer consent. A complete supported quote in server paymentMode test or stripe_test creates public snapshot.checkout and pending sandbox payment immediately, without waiting for an operator-issued offer. The checkout receipt binds kind quoted_order, quoteHash, executionHash, amountCents, currency, acceptedAt, termsVersion and terms. It captures no money and does not release physical work. The private consenting identity/audit receipt is never returned. Omitting checkout saves only a supported fully priced unpaid request. Continue that record through /orders/{id}/checkout after explicit acceptance. No lab offer is required. Null-priced or unsupported scope is rejected even without checkout; choose a supported alternative. checkout with an incomplete/custom quote returns CHECKOUT_REVIEW_REQUIRED; unconfigured mode returns TEST_PAYMENTS_DISABLED; a changed quote hash returns QUOTE_CHANGED. Invalid or unsupported recipes still fail. The original brief is frozen from the owned generated source, or originalBrief for exact recipes; legacy absence is not inferred. relatedOrderId links a new owned request when agreed scope changes. Same-key retries recover the original request. Referencing a saved idea or website generation requires ideas:read in addition to the operation scopes; referencing a saved order requires orders:read. Source scopes are checked before retrieval and idempotent replay. Fully supplied ingredient/prompt inputs do not require ideas:read. An owned guest-browser generation is accessible only through that guest session capability, not through an API-key exception.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[-a-zA-Z0-9_.:]{8,128}$" }, "description": "Unique per workspace and operation. Reuse with exactly the same normalized request after network failures. No automatic expiration in v2." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceOrder" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/RequestSubmission" } }, "required": [ "order" ] } } } }, "201": { "description": "Service order created with a frozen quote and exact recipes; explicit checkout consent initializes pending payment for the configured sandbox provider when supported.", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/RequestSubmission" } }, "required": [ "order" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "AUTHENTICATION_REQUIRED: guest browser or missing verified account email; or missing, revoked, expired or invalid API key. Log in before browser ordering. API-key clients continue to authenticate and supply contactEmail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listServiceOrders", "summary": "List owned service orders and their derived orderStatus", "description": "Required scope: orders:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/RequestSubmission" } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{id}": { "get": { "operationId": "getServiceOrder", "summary": "Read an owned service order or withdrawn receipt", "description": "Required scope: orders:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. snapshot.results contains BatchReport, including every expected preparation, all actual shared evidence and correction history. No report fields are invented when work has not been recorded. No email is automatically sent. snapshot.output contains the latest published overall notes, photos and optional per-recipe recipeResults when present; internal drafts and publication history are not returned.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/RequestSubmission" } }, "required": [ "order" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{id}/checkout": { "post": { "operationId": "prepareSavedQuoteCheckout", "summary": "Accept the original saved quote and start checkout for a previously saved priced request", "description": "Required scope: orders:read and orders:write. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. Show the saved recipe, total and trial terms before explicit acceptance. Send current revision, saved quoteHash, acceptQuote:true and a stable Idempotency-Key. The original frozen price is retained; no current-price recalculation or lab confirmation is needed. Requires active owned order, supported sources and a configured sandbox mode (test or stripe_test). A real revised or accepted offer cannot be bypassed. Replay the same body/key after interruption. This initializes pending payment for the configured sandbox provider only, never claims paid or physical work.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[-a-zA-Z0-9_.:]{8,128}$" }, "description": "Unique per workspace and operation. Reuse with exactly the same normalized request after network failures. No automatic expiration in v2." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedQuoteCheckout" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/RequestSubmission" } }, "required": [ "order" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lab-status": { "get": { "operationId": "getLabStatus", "summary": "Check whether the lab accepts new submissions and test checkout is enabled", "security": [], "responses": { "200": { "description": "Current intake and payment mode. New submissions and payment actions are independently checked at commit time.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LabStatus" } } } }, "503": { "description": "Availability could not be verified; new intake fails closed." } } } }, "/orders/{id}/test-payment": { "post": { "operationId": "simulateOrderPayment", "summary": "Record a simulated test checkout outcome; no money is charged", "description": "Required scope: orders:read and orders:write. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. Available only when server paymentMode is test and the lab is accepting orders. Requires an owned, active service order with either saved quoted-order checkout consent and matching unbound simulated payment, or an explicitly accepted final offer and matching offer-bound simulated payment. Direct quote checkout validates the private consent receipt, exact frozen recipe and quote fingerprint, current source state, amount and currency. Review checkout validates the current accepted offer ID/hash and amount. A newly issued review offer prevents the direct quote path until reviewed and accepted. Guests cannot use this endpoint. Send only outcome: succeeded, failed or cancelled. Caller amounts, provider fields and card details are rejected. No financial provider is contacted; fundsCaptured is always false. This is not Stripe test mode. Failure and cancellation permit another attempt with a fresh key; succeeded is terminal. At most 20 outcomes can be recorded per order. Requests are transactionally audited and revision guarded. Use the same key and unchanged body after an uncertain response: an exact saved response is replayed even if the lab is paused, mode changes, or the order later closes. A replay may describe an earlier failed/cancelled state; GET /orders/{id} for canonical current state. Withdrawal prevents new attempts; retained owner receipts and exact replay remain accessible. Closed orders and cancelled fulfillment reject new attempts with ORDER_CLOSED. Other 409 codes include TEST_PAYMENTS_DISABLED, TEST_PAYMENT_UNAVAILABLE, QUOTE_REQUIRED, CHECKOUT_REVIEW_REQUIRED, CHECKOUT_CONSENT_REQUIRED, CHECKOUT_QUOTE_CHANGED, PAYMENT_OFFER_MISMATCH, OFFER_ACCEPTANCE_REQUIRED, PAYMENT_QUOTE_MISMATCH, PAYMENT_ALREADY_SUCCEEDED, INVALID_PAYMENT_STATE, PAYMENT_ATTEMPT_LIMIT, LAB_PAUSED, PAYMENT_CHANGED and IDEMPOTENCY_CONFLICT. A successful simulation returns orderStatus ordered_pending_lab and fulfillmentStatus pending, with snapshot.fulfillment.status pending_lab. It never prepares, dispatches or creates report evidence. Failed or cancelled attempts stay awaiting_checkout. REST only: no dedicated MCP payment tool is currently exposed.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[-a-zA-Z0-9_.:]{8,128}$" }, "description": "Unique per workspace and operation. Reuse with exactly the same normalized request after network failures. No automatic expiration in v2." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulateTestPayment" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestPaymentResult" } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "AUTHENTICATION_REQUIRED: authenticate as the owner; guest browser sessions cannot perform test checkout.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{id}/stripe-checkout": { "post": { "operationId": "createStripeCheckout", "summary": "Open hosted Stripe sandbox Checkout for the exact accepted order total", "description": "Required scope: orders:read and orders:write. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. Requires server paymentMode stripe_test, configured sandbox secrets, an open lab and an owned active order with accepted saved-quote consent or an accepted historical final offer. Send only the current payment.id as paymentId. No caller amount, currency, success URL or card details are accepted. The server copies the frozen accepted USD total and uses durable attempt records and Stripe idempotency. Persist the body and Idempotency-Key before sending; retry them unchanged after uncertainty. Return checkout.url to the customer for interactive checkout; redirect only to HTTPS checkout.stripe.com. Read GET /orders/{id} after return and display canonical payment and orderStatus. Never treat the redirect or query string as proof of payment. checkout is null and awaitingConfirmation true when the session is complete but its signed webhook has not yet confirmed the order. Sessions expire about 31 minutes after creation. Cancellation reuses an open session; confirmed expiry requires a new attempt key. Unknown remote outcomes older than 23 hours require operator reconciliation and never create a replacement session automatically. Verified success enters Ordered - Pending Lab unless a later order change requires an operator hold; it does not start work or ship samples. Pausing intake blocks new checkouts while signed webhook reconciliation continues. This endpoint supports sandbox keys and livemode false only; fundsCaptured remains false. Native MCP has no dedicated payment tool: agents may create the session with REST and hand the hosted URL to the customer.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[-a-zA-Z0-9_.:]{8,128}$" }, "description": "Unique per workspace and operation. Reuse with exactly the same normalized request after network failures. No automatic expiration in v2." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeCheckout" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeCheckoutResult" } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State conflict such as LAB_PAUSED, STRIPE_PAYMENT_UNAVAILABLE, PAYMENT_ALREADY_SUCCEEDED, STRIPE_CHECKOUT_EXPIRED, STRIPE_CHECKOUT_ALREADY_ACTIVE, CHECKOUT_CHANGED, PAYMENT_QUOTE_MISMATCH or IDEMPOTENCY_CONFLICT. Refresh the owned order and follow the returned code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "STRIPE_NOT_CONFIGURED, STRIPE_UNAVAILABLE or STRIPE_RECOVERY_REQUIRED. Follow retryable and Retry-After. Recover uncertain recent writes using the original body/key; STRIPE_RECOVERY_REQUIRED needs operator reconciliation before another attempt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/stripe/webhook": { "post": { "operationId": "receiveStripeWebhook", "summary": "Receive signed Stripe sandbox Checkout session events", "servers": [ { "url": "https://labs.deconfound.com" } ], "security": [], "description": "Stripe-only server callback using Snapshot event payloads, independently of customer authentication and lab intake. A valid Stripe-Signature is required; the server verifies the raw body, sandbox flag and saved session binding. Handles checkout.session.completed, checkout.session.async_payment_succeeded, checkout.session.async_payment_failed and checkout.session.expired. Reconciles against the current session and deduplicates event IDs. Real-money events are rejected. Customers and agents do not call this endpoint.", "parameters": [ { "name": "Stripe-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "livemode": { "const": false }, "data": { "type": "object", "properties": { "object": { "type": "object", "additionalProperties": true } }, "required": [ "object" ] } }, "required": [ "id", "type", "livemode", "data" ] } } } }, "responses": { "200": { "description": "Event received, already processed or not applicable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "const": true }, "ignored": { "type": "boolean" } }, "required": [ "received" ] } } } }, "400": { "description": "Invalid signature, event or sandbox payload." }, "409": { "description": "Session does not match its saved checkout." }, "413": { "description": "Raw webhook body exceeds 256 KiB." }, "415": { "description": "Content-Type must be application/json." }, "503": { "description": "Configuration, provider, database or reconciliation unavailable. Stripe should retry." } } } }, "/admin/orders/{id}/assessment-preview": { "post": { "operationId": "previewServiceAssessment", "summary": "Preview the exact customer report with a draft criterion assessment", "description": "Required scope: authorized operator AAL2 browser session only. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. Read-only validation with the same evidence, accepted-contract integrity and revision checks as publication. It never saves a draft, readiness timestamp, history or notification. No Idempotency-Key is required. API keys and MCP cannot call this operator surface.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordServiceAssessment" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAssessmentPreview" } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/orders/{id}/assessment": { "post": { "operationId": "publishServiceAssessment", "summary": "Publish or explicitly correct the criterion-by-criterion trial assessment", "description": "Required scope: authorized operator AAL2 browser session only. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. Requires an active reviewed order, all expected batch records, the exact canonical accepted offer ID/hash and current revision. Include exactly one row for every agreed criterion and ordered recipe version. An assessed verdict must reference the required field in every current replicate of that version; superseded, foreign, duplicate or missing observations are rejected. Instrument evidence requires numeric readings with method, instrument, calibration and time. All readings within the agreed inclusive range requires achieved; none within requires not_achieved; mixed readings require partly_achieved. Null is missing and requires not_assessed with an honest explanation and empty evidence. preferred or no_clear_winner requires at least one common assessed criterion across every version; no winner is inferred by the server. Corrections require the latest supersedesId and a nonempty correctionReason; old versions remain immutable. A new batch correction makes the previous assessment stale and removes current report readiness. Publishing sets current reportReadyAt; firstReportReadyAt is recorded only once and survives corrections. Scheduling a report date never publishes it. Send the same Idempotency-Key and identical body after an ambiguous response: retries return current results plus the original assessmentId, without duplicating history or notifications. Validation, revision or receipt persistence failure saves nothing. A private manual notification task is created; no email, model, payment or physical test is performed. API keys and MCP cannot publish. Errors include CRITERIA_NOT_AGREED, OFFER_CHANGED, OFFER_CONTRACT_CHANGED, REPORT_INCOMPLETE, CRITERIA_MISMATCH, ASSESSMENT_EVIDENCE, DUPLICATE_EVIDENCE, VERDICT_CONFLICT, CRITERION_RANGE_MISSING, COMPARISON_EVIDENCE, COMPARISON_MISMATCH, INVALID_CORRECTION, ASSESSMENT_HISTORY_LIMIT, REPORT_TOO_LARGE, REVISION_CONFLICT and IDEMPOTENCY_CONFLICT.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[-a-zA-Z0-9_.:]{8,128}$" }, "description": "Unique per workspace and operation. Reuse with exactly the same normalized request after network failures. No automatic expiration in v2." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordServiceAssessment" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceAssessmentResult" } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{id}/results": { "get": { "operationId": "getServiceBatchRecords", "summary": "Read published output plus separately recorded advanced batch evidence", "description": "Required scope: orders:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. fulfillmentStatus and output.completedAt identify simple completion. output.recipeResults, when present, contains per-recipe descriptions and photoIds referencing output.photos; legacy notes/photo outputs remain supported. output.recipeResults[].evidence contains the actual preparation submitted through the simple workflow. results.status refers separately to advanced batch records and can remain not_started. No measurements are inferred. Draft output is never included.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid" }, "revision": { "type": "integer" }, "fulfillmentStatus": { "type": "string" }, "results": { "$ref": "#/components/schemas/BatchReport" }, "output": { "anyOf": [ { "$ref": "#/components/schemas/SimpleOrderOutput" }, { "type": "null" } ] } }, "required": [ "orderId", "revision", "fulfillmentStatus", "results", "output" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/orders/{id}/results": { "post": { "operationId": "shareBatchRecord", "summary": "Share one actual batch record or a reasoned correction", "description": "Required scope: authorized operator browser session only. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. Requires reviewed order, current submission revision, exact expected recipeId/batchId and every ingredient including water. Include a value or explicit missing reason for actual mass and all requested metrics. Saving shares immediately; no email. Same-key retry returns the current report. Corrections require supersedesId and correctionReason. API keys and MCP cannot write records.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[-a-zA-Z0-9_.:]{8,128}$" }, "description": "Unique per workspace and operation. Reuse with exactly the same normalized request after network failures. No automatic expiration in v2." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordBatch" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid" }, "revision": { "type": "integer" }, "fulfillmentStatus": { "type": "string" }, "results": { "$ref": "#/components/schemas/BatchReport" }, "output": { "anyOf": [ { "$ref": "#/components/schemas/SimpleOrderOutput" }, { "type": "null" } ] } }, "required": [ "orderId", "revision", "fulfillmentStatus", "results", "output" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{id}/photos/{photoId}": { "get": { "operationId": "readBatchPhoto", "summary": "Read an authenticated batch photo", "description": "Required scope: orders:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "photoId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Private image; no-store. Customers can only retrieve photos shared in their active order.", "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/orders/{id}/photos/{photoId}": { "get": { "operationId": "readOperatorBatchPhoto", "summary": "Read an authenticated batch photo", "description": "Required scope: authorized operator browser session. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "photoId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Private image; no-store. Customers can only retrieve photos shared in their active order.", "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "discardPendingBatchPhoto", "summary": "Discard an unused draft photo; published evidence cannot be discarded", "description": "Required scope: authorized operator AAL2 browser session only. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "photoId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/orders/{id}/photos": { "post": { "operationId": "uploadBatchPhoto", "summary": "Upload a private JPEG, PNG or WebP, at most 2 MiB", "description": "Required scope: authorized operator browser session only. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. An immutable Idempotency-Key identifies the upload; reuse it with identical bytes after a lost response. Uploaded images are normalized to remove location/device metadata. List pending photos to restore an unfinished report; published evidence remains private and retained.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[-a-zA-Z0-9_.:]{8,128}$" }, "description": "Unique per workspace and operation. Reuse with exactly the same normalized request after network failures. No automatic expiration in v2." }, { "name": "X-Batch-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "photo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] } }, "required": [ "photo" ] } } } }, "201": { "description": "Photo stored privately; attach its ID and caption to this batch record to share.", "content": { "application/json": { "schema": { "type": "object", "properties": { "photo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ] } }, "required": [ "photo" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } } } } }, "get": { "operationId": "listPendingBatchPhotos", "summary": "List reusable pending photos for an expected preparation", "description": "Required scope: authorized operator AAL2 browser session only. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "batchId", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/formulations": { "get": { "operationId": "listSavedFormulations", "summary": "List owned website and API recipes with cursor pagination", "description": "Required scope: ideas:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "enum": [ "generation", "idea" ] }, "revision": { "type": "integer" }, "name": { "type": "string" }, "prompt": { "type": "string" }, "status": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "source", "revision", "name", "prompt", "status", "createdAt" ] } }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/formulations/{id}": { "get": { "operationId": "getSavedFormulation", "summary": "Reopen an owned saved formulation with its current customer quote", "description": "Required scope: ideas:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "enum": [ "generation", "idea" ] }, "revision": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "suggestion": { "type": "object" } }, "required": [ "id", "source", "revision", "createdAt", "suggestion" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/refinement-context": { "get": { "operationId": "getRefinementContext", "summary": "Load an owned canonical recipe and recorded context for a new refinement", "description": "Required scope: ideas:read; orders:read additionally for source=order. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. Reads the owned source rather than trusting browser-supplied ingredient quantities. reference includes its current revision and selected recipe/variant; retain it for subsequent browser refinement. Order sources carry exact saved quantities, process, accepted criteria and current evidence, with prior supplier details removed. Stale corrected conclusions are identified and not reused as current assessments. The original request and explicit ingredient exclusions are carried forward when the owned source exists. previousUrl returns to the source and relatedOrderId links follow-up work. This read creates no recipe, quote, order or model call. Unknown/repeated query fields are rejected; missing, foreign or unavailable sources return an error. Refinement produces a new candidate requiring its own quote and acceptance; it never edits accepted work.", "parameters": [ { "name": "source", "in": "query", "required": true, "schema": { "enum": [ "generation", "idea", "order" ] } }, { "name": "id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "recipeId", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, { "name": "variantId", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 64 } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefinementContext" } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/orders/{id}/release": { "get": { "operationId": "getServiceRelease", "summary": "Read exact received lots, reviewed method and release state", "description": "Required scope: authorized operator AAL2 browser session only. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "reviewServiceRelease", "summary": "Review execution and reserve exact received lots", "description": "Required scope: authorized operator AAL2 browser session only. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. Requires reviewed active order, complete quote, configured payment or explicit test-only override, every recipe and exact source-verified lot including water, complete BenchSettings and applicable carbonation source/equipment. The server checks minimum weighing, current source holds, expiry and available stock and reserves atomically. Re-review replaces reservations before work starts; started work cannot be rewritten. Preparing rechecks the frozen release. Report publication reconciles actual additions; corrections retain usage history. Send the current revision and an immutable Idempotency-Key for retries. API keys cannot authorize this operator action. Errors include RELEASE_REQUIRED, LOT_SOURCE_MISMATCH, LOT_NOT_READY, STALE_WORKSHEET, PAYMENT_REQUIRED, QUOTE_REQUIRED and RELEASE_CHANGED. Explicitly accepted final offer is required before new work, including test-payment overrides. A migration marker permits already-started legacy work to finish without fabricating acceptance. Reviewed offer methods cannot be replaced during release. GET also includes private reviewed measurementMethods.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[-a-zA-Z0-9_.:]{8,128}$" }, "description": "Unique per workspace and operation. Reuse with exactly the same normalized request after network failures. No automatic expiration in v2." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseServiceWork" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/RequestSubmission" } }, "required": [ "order" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/orders/{id}/photos/cleanup": { "post": { "operationId": "cleanupAbandonedBatchPhotos", "summary": "Run bounded cleanup of eligible abandoned uploads for this order", "description": "Required scope: authorized operator AAL2 browser session only. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. Send an empty JSON object. Grace periods and published/correction references are checked again before deletion. Normal cleanup also runs on the hourly Worker schedule.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } } } } }, "/orders/{id}/delivery": { "post": { "operationId": "updateOrderDelivery", "summary": "Confirm the owned shipping address or report a sample arrival issue", "description": "Required scope: orders:read and orders:write. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. Pass the current order revision and a unique Idempotency-Key. Retry an uncertain response using the same key and identical body. Full address must retain the quoted country, region and postalCode; changing them returns DESTINATION_CHANGED and requires a revised quote. Address confirmation invalidates any unshipped package approval and never reroutes existing shipments. Arrival issues are recorded for lab review; this operation does not send an email or issue a refund. GET /orders/{id} exposes snapshot.delivery with reportDueOn, confirmed address, shipment packets, tracking, arrival issues and timeline. Report availability is separate from sample dispatch.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[-a-zA-Z0-9_.:]{8,128}$" }, "description": "Unique per workspace and operation. Reuse with exactly the same normalized request after network failures. No automatic expiration in v2." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerDeliveryCommand" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/RequestSubmission" } }, "required": [ "order" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/orders/{id}/delivery": { "post": { "operationId": "manageOrderDelivery", "summary": "Schedule reports, approve sample packages, record dispatch, delivery, remedies and manual notifications", "description": "Required scope: authorized operator AAL2 browser session only. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. API keys cannot perform operator actions. Package approval requires customer-confirmed address, current published batch records, one sample per recipe version within quoted mass and measured remaining batch mass after prior shipments, reviewed allergen/storage/use/packaging information, and a documented transportQualification. It must identify the validation record and package configuration, validity dates, temperature interval, maximum total holding time through arrival and transit duration covering expected transit. Each sample carries its holding-temperature record, observed minimum/maximum, and the exact researchLabel RESEARCH ONLY — NOT FOR HUMAN OR ANIMAL CONSUMPTION. Unknown or out-of-limit temperatures, stale/expired qualification, unsupported actual product/dose qualification and excess holding time block approval/dispatch. Dispatch requires the matching current package approval for today, a succeeded payment matching the current quote and configured mode, a started execution release with current source/lot checks, and an order without a hold or cancellation request. Dispatch also requires packingEvidence: actual packing within the last hour, a temperature measured after packing and within the last 30 minutes, a value within the qualified range, a record reference, and explicit confirmation that physical labels are applied, the package matches the qualification, and samples/seals are intact. These attestations enforce recorded limits; they do not invent a validation study or grant regulatory permission. Legacy package approvals lacking this evidence must be renewed. Calendar dates use America/Los_Angeles. Recorded shipment address and evidence remain frozen. Report dates, report publication, dispatch, arrival issues and issue resolutions create private manual notification tasks; record_notification confirms an actual external contact, never sends one. HTTPS tracking links cannot contain credentials. Errors include TRANSPORT_QUALIFICATION_REQUIRED, TRANSPORT_QUALIFICATION_INVALID, STORAGE_TEMPERATURE_OUTSIDE_LIMIT, RESEARCH_LABEL_REQUIRED, HOLD_TIME_EXCEEDED, PACKING_EVIDENCE_STALE, DISPATCH_TEMPERATURE_OUTSIDE_LIMIT, PACKING_EVIDENCE_REQUIRED, PHYSICAL_QUALIFICATION_REQUIRED, ADDRESS_UNCONFIRMED, PACKAGE_NOT_APPROVED, REPORT_INCOMPLETE, SAMPLE_RECORD_CHANGED, SAMPLE_MASS_EXCEEDED, BATCH_MASS_NOT_MEASURED, PAYMENT_REQUIRED, PAYMENT_QUOTE_MISMATCH, PAYMENT_MODE_MISMATCH, WORK_NOT_STARTED, LOT_NOT_READY, ORDER_ON_HOLD, DISPATCH_DATE_CHANGED, REVISION_CONFLICT and IDEMPOTENCY_CONFLICT. No carrier, payment or email provider is invoked.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[-a-zA-Z0-9_.:]{8,128}$" }, "description": "Unique per workspace and operation. Reuse with exactly the same normalized request after network failures. No automatic expiration in v2." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorDeliveryCommand" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/RequestSubmission" } }, "required": [ "order" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{id}/offers": { "get": { "operationId": "getOrderOffers", "summary": "Read current and historical final offers", "description": "Required scope: orders:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinalOfferView" } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{id}/offers/{offerId}/accept": { "post": { "operationId": "acceptOrderOffer", "summary": "Explicitly accept the exact current unexpired final offer", "description": "Required scope: orders:read and orders:write. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. Show the complete offer and obtain explicit requester agreement before sending confirm:true. Send current order revision and offerHash with a distinct immutable Idempotency-Key. Acceptance freezes the exact recipes, methods, criteria, one iteration, total including tax/shipping, report date, and remedy terms. It initializes an offer-bound pending simulation only in test mode. Acceptance itself charges nothing and does not release work. Expired, superseded, revoked, changed, withdrawn and unauthorized offers are rejected. Same-key retries recover the saved result; a changed body returns IDEMPOTENCY_CONFLICT. Same-scope acceptance must match the saved order quote; a historical unaccepted offer with a different price must be reissued. Already accepted agreements remain unchanged. Errors include ORDER_QUOTE_LOCKED, SAVED_QUOTE_INVALID, OFFER_NOT_CURRENT, OFFER_EXPIRED, OFFER_CHANGED, REVISION_CONFLICT, LAB_PAUSED and AGREED_WORK_LOCKED.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "offerId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[-a-zA-Z0-9_.:]{8,128}$" }, "description": "Unique per workspace and operation. Reuse with exactly the same normalized request after network failures. No automatic expiration in v2." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptFinalOffer" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "offer": { "$ref": "#/components/schemas/FinalServiceOffer" }, "order": { "$ref": "#/components/schemas/RequestSubmission" } }, "required": [ "offer", "order" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/orders/{id}/offers": { "get": { "operationId": "getOperatorOrderOffers", "summary": "Read offers and editable defaults", "description": "Required scope: authorized operator AAL2 browser session. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinalOfferView" } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "issueFinalOffer", "summary": "Issue or revoke a versioned final offer", "description": "Required scope: authorized operator AAL2 browser session. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. Operator review is not customer acceptance. Fixed recipes must satisfy current source/dose/process bounds. Precision exceptions require verified capable BenchSettings; instrument promises require measurementMethods and matched criteria ranges. Revised formulas require an explicit alternative and changes. An unchanged request retains its original saved trial, shipping, tax and total amounts, even if pricing policies later change. Price-only changes return ORDER_QUOTE_LOCKED. Changed scope or an unresolved original quote requires an explicit new quote at the current margin floor; tax treatment is explicit. Inconsistent saved price data returns SAVED_QUOTE_INVALID. Unsupported shipping needs a reviewed mass/allowance or a report-only revision. Accepted, released or started work is immutable; use a linked new request. Legacy missing brief/consent stays not_recorded. A matching unstarted legacy simulated receipt is retained separately; actual acceptance now starts a new offer-bound simulation. The accepted report date stays originalReportDueOn while later forecasts use reportDueOn.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[-a-zA-Z0-9_.:]{8,128}$" }, "description": "Unique per workspace and operation. Reuse with exactly the same normalized request after network failures. No automatic expiration in v2." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinalOfferCommand" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "type": "object", "properties": { "offer": { "$ref": "#/components/schemas/FinalServiceOffer" }, "order": { "$ref": "#/components/schemas/RequestSubmission" } }, "required": [ "offer", "order" ] } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/capacity": { "get": { "operationId": "getBenchCapacity", "summary": "Read daily planned work and unresolved legacy workload", "description": "Required scope: authorized operator AAL2 browser session. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "changeBenchCapacity", "summary": "Configure work budgets or allocate overdue/unallocated accepted work", "description": "Required scope: authorized operator AAL2 browser session. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. Default daily plan is 6 preparations and 180 estimated bench minutes, America/Los_Angeles. Only operator-issued offers hold slots; free intake does not. Unaccepted holds expire with the offer; explicit acceptance retains a booked slot. Superseding/revoking an offer or cancelling unstarted work releases unused capacity. Completed/started-cancelled work retains its daily allocation. Unknown or overdue accepted legacy work blocks new holds until explicitly scheduled. Original accepted bench/report dates are immutable; current bench forecast/reason and manual notification are recorded on rescheduling. All writes use immutable idempotency keys and atomic budget guards. Capacity never opens or closes manual intake. Errors include WORK_CAPACITY_FULL, WORK_CAPACITY_EXPIRED, WORK_SCHEDULE_UNRESOLVED, CAPACITY_CHANGED and REVISION_CONFLICT.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[-a-zA-Z0-9_.:]{8,128}$" }, "description": "Unique per workspace and operation. Reuse with exactly the same normalized request after network failures. No automatic expiration in v2." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BenchCapacityCommand" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": {} } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/orders/{id}/output": { "get": { "operationId": "getOrderOutput", "summary": "Read published recipe descriptions, sample photos and overall analysis", "description": "Required scope: orders:read. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. Draft output is private and returns null until completion. Optional output.recipeResults links each description and its photoIds to an ordered recipe. Resolve photoIds through output.photos; unassigned top-level photos remain available as general report photos. Older published outputs may contain notes/photos without recipeResults and remain valid. New publications include actual preparation evidence and explicit tasting or omission; older publications remain readable without inferred evidence. This records operator observations, not a safety certification or payment. Photo URLs require the same order owner credentials.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleOrderOutputView" } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/admin/orders/{id}/output": { "get": { "operationId": "getOperatorOrderOutput", "summary": "Read a private output draft and the last published output", "description": "Required scope: authorized operator AAL2 browser session only. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorOrderOutputView" } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Body exceeds 64 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "saveOrderOutput", "summary": "Save a private draft or complete the order and publish its output", "description": "Required scope: authorized operator AAL2 browser session only. Machine calls use X-Deconfound-Api-Key. Lab permissions are operator-only. Service orders only. Operator GET includes current per-recipe readiness (qualified and issues) so missing qualification is visible before work; customers do not receive this internal review. Save incomplete observations as action save; they remain private. action complete publishes a report and marks fulfillmentStatus complete only after every recipe has a condition description, photo or documented omission, and actual preparation evidence for every batch. Evidence includes exact source IDs matching the ordered products, lot and real use-by dates covering preparation, every actual ingredient mass, recovered batch mass, equipment/method, actual steps and deviations. Prepared times must be real, after order creation and not future. Missing or stale product qualification, unsupported actual operations, unrecorded tasting, unexplained quantity changes and unknown lots block completion. Tasted requires a recorded assessment reference, explicit approval and actual observations; otherwise use not_tasted with a reason. Current catalog qualification is rechecked atomically at publication. Existing payments and actual inventory consumption remain unchanged; unused reservations are released and capacity allocations completed atomically. A new customer quote-confirmation step is not introduced. JSON bodies are limited to 384 KiB, with structural bounds before schema traversal. Historical publications and exact committed idempotent retries remain intact; new legacy notes-only completions are rejected. Held, closed, cancelled or withdrawal-pending orders cannot complete. Photos must be ready uploads from the same order and recipe batch. Prior publications remain in private history. Error codes include RECIPE_RESULTS_INCOMPLETE, PREPARATION_EVIDENCE_REQUIRED, READINESS_REQUIRED, EXACT_PRODUCT_REQUIRED, LOT_EXPIRY_REQUIRED, DEVIATION_REQUIRED, TASTING_STATUS_REQUIRED, TASTING_REVIEW_REQUIRED, SAMPLE_DESCRIPTION_REQUIRED, SAMPLE_PHOTO_REQUIRED, PHYSICAL_QUALIFICATION_REQUIRED, PROCESS_NOT_QUALIFIED, BATCH_MASS_INVALID, PREPARATION_DATE_INVALID, PHOTO_RECIPE_MISMATCH, PHOTO_NOT_FOUND and REVISION_CONFLICT. A private manual notification task is created; no email is sent. Customer keys and MCP cannot publish operator output.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[-a-zA-Z0-9_.:]{8,128}$" }, "description": "Unique per workspace and operation. Reuse with exactly the same normalized request after network failures. No automatic expiration in v2." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleOrderOutputCommand" } } } }, "responses": { "200": { "description": "Success. Creation replay returns the current authorized resource, or a stable receipt when the key lacks read scope. Command replay requires the operation scopes again and returns its saved response unless documented otherwise.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorOrderOutputView" } } } }, "400": { "description": "Invalid JSON, header, resource ID or query", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, revoked, expired or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient scope, session required or cross-origin write", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found in this workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "Unsupported method; see Allow", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "State, revision, availability or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds 384 KiB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Schema, formulation, ingredient or result validation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited; see Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "AI provider returned invalid output", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "AI or storage dependency unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "AI timeout or generation lease expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "DeconfoundKey": { "type": "apiKey", "in": "header", "name": "X-Deconfound-Api-Key" } }, "schemas": { "CreateTrial": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "decision": { "type": "string", "minLength": 3, "maxLength": 1500 }, "audience": { "default": "", "type": "string", "maxLength": 500 }, "benchmark": { "default": "", "type": "string", "maxLength": 500 }, "constraints": { "default": "", "type": "string", "maxLength": 1000 } }, "required": [ "name", "decision" ], "additionalProperties": false }, "TrialAction": { "oneOf": [ { "type": "object", "properties": { "action": { "type": "string", "const": "link_order" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "orderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "role": { "default": "candidate", "type": "string", "enum": [ "candidate", "reference" ] } }, "required": [ "action", "revision", "orderId", "label" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "select" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "sampleId": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "reason": { "type": "string", "minLength": 3, "maxLength": 1500 } }, "required": [ "action", "revision", "sampleId", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "record_tasting" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "sampleId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "batchId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "panelistCode": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[a-zA-Z0-9_-]+$" }, "sessionCode": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[a-zA-Z0-9_-]+$" }, "liking": { "type": "integer", "minimum": 1, "maximum": 9 }, "flavorFit": { "type": "integer", "minimum": 1, "maximum": 9 }, "sweetness": { "type": "integer", "minimum": -2, "maximum": 2 }, "tartness": { "type": "integer", "minimum": -2, "maximum": 2 }, "servingTemperatureC": { "type": "number", "minimum": 0, "maximum": 80 }, "conditions": { "type": "string", "minLength": 3, "maxLength": 500 }, "notes": { "default": "", "type": "string", "maxLength": 1000 }, "tastedAt": { "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))$" }, "reviewedForTasting": { "type": "boolean", "const": true }, "supersedesId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "correctionReason": { "type": "string", "minLength": 3, "maxLength": 500 } }, "required": [ "action", "revision", "sampleId", "batchId", "panelistCode", "sessionCode", "liking", "flavorFit", "sweetness", "tartness", "servingTemperatureC", "conditions", "tastedAt", "reviewedForTasting" ], "additionalProperties": false } ] }, "TrialSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "decision": { "type": "string" }, "revision": { "type": "integer" }, "sampleCount": { "type": "integer" }, "tastingCount": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "decision", "revision", "sampleCount", "tastingCount", "createdAt", "updatedAt" ] }, "TrialSample": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "orderId": { "type": "string", "format": "uuid" }, "orderRevision": { "type": "integer" }, "label": { "type": "string" }, "role": { "enum": [ "candidate", "reference" ] }, "formulaHash": { "type": "string" }, "worksheetHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "linkedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "code", "orderId", "orderRevision", "label", "role", "formulaHash", "worksheetHash", "linkedAt" ] }, "Tasting": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sampleId": { "type": "string", "format": "uuid" }, "batchId": { "type": "string", "format": "uuid" }, "panelistCode": { "type": "string" }, "sessionCode": { "type": "string" }, "liking": { "type": "integer" }, "flavorFit": { "type": "integer" }, "sweetness": { "type": "integer" }, "tartness": { "type": "integer" }, "servingTemperatureC": { "type": "number" }, "conditions": { "type": "string" }, "notes": { "type": "string" }, "tastedAt": { "type": "string", "format": "date-time" }, "supersedesId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "correctionReason": { "type": "string" }, "actor": { "type": "string" }, "recordedAt": { "type": "string", "format": "date-time" }, "orderRevision": { "type": "integer" }, "worksheetHash": { "type": "string" }, "formulaHash": { "type": "string" } }, "required": [ "id", "sampleId", "batchId", "panelistCode", "sessionCode", "liking", "flavorFit", "sweetness", "tartness", "servingTemperatureC", "conditions", "notes", "tastedAt", "supersedesId", "correctionReason", "actor", "recordedAt", "orderRevision", "worksheetHash", "formulaHash" ] }, "Trial": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "decision": { "type": "string" }, "audience": { "type": "string" }, "benchmark": { "type": "string" }, "constraints": { "type": "string" }, "revision": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "samples": { "type": "array", "items": { "$ref": "#/components/schemas/TrialSample" } }, "tastings": { "type": "array", "items": { "$ref": "#/components/schemas/Tasting" } }, "selection": { "anyOf": [ { "type": "object", "properties": { "sampleId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "reason": { "type": "string" }, "evidenceRevision": { "type": "integer" }, "orderRevisions": { "type": "object", "additionalProperties": { "type": "integer" } }, "actor": { "type": "string" }, "at": { "type": "string", "format": "date-time" } }, "required": [ "sampleId", "reason", "evidenceRevision", "orderRevisions", "actor", "at" ] }, { "type": "null" } ] }, "history": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string" }, "actor": { "type": "string" }, "at": { "type": "string", "format": "date-time" } }, "required": [ "action", "actor", "at" ] } } }, "required": [ "id", "name", "decision", "audience", "benchmark", "constraints", "revision", "createdAt", "updatedAt", "samples", "tastings", "selection", "history" ] }, "TrialComparison": { "type": "object", "properties": { "pairedPanelists": { "type": "integer" }, "pairedSessions": { "type": "integer" }, "totalPanelists": { "type": "integer" }, "totalSessions": { "type": "integer" }, "selectionStale": { "type": "boolean" }, "samples": { "type": "array", "items": { "type": "object", "properties": { "sampleId": { "type": "string", "format": "uuid" }, "code": { "type": "string" }, "role": { "type": "string" }, "label": { "type": "string" }, "observations": { "type": "integer" }, "meanLiking": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "meanFlavorFit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "meanSweetness": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "meanTartness": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "pairedMeanLiking": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "pairedMeanFlavorFit": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "sampleId", "code", "role", "label", "observations", "meanLiking", "meanFlavorFit", "meanSweetness", "meanTartness", "pairedMeanLiking", "pairedMeanFlavorFit" ] } }, "limitations": { "type": "string" } }, "required": [ "pairedPanelists", "pairedSessions", "totalPanelists", "totalSessions", "selectionStale", "samples", "limitations" ], "description": "Complete-case sessions across every linked sample including reference; average repeated complete sessions per person before paired means. Null is missing, not zero. Descriptive observations, not significance or consumer validation. Check selectionStale after any trial or linked-order update." }, "TrialReport": { "type": "object", "properties": { "schemaVersion": { "const": "flavor-trial-1" }, "generatedAt": { "type": "string", "format": "date-time" }, "trial": { "$ref": "#/components/schemas/Trial" }, "comparison": { "$ref": "#/components/schemas/TrialComparison" }, "orders": { "type": "array", "items": { "type": "object", "properties": { "sampleId": { "type": "string", "format": "uuid" }, "order": { "$ref": "#/components/schemas/LabOrder" }, "results": { "$ref": "#/components/schemas/Evaluation" }, "methodChangedSinceLink": { "type": "boolean" }, "tastingBatches": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "sampleId", "order", "results", "methodChangedSinceLink", "tastingBatches" ] } }, "limitations": { "type": "string" } }, "required": [ "schemaVersion", "generatedAt", "trial", "comparison", "orders", "limitations" ] }, "RecipeGap": { "type": "object", "properties": { "variantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "code": { "type": "string" }, "capability": { "type": "string" }, "message": { "type": "string" } }, "required": [ "variantId", "code", "message" ] }, "RecipeAlternative": { "type": "object", "properties": { "id": { "type": "string" }, "variantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "type": "string" }, "description": { "type": "string" }, "changes": { "type": "array", "items": { "type": "string" } }, "action": { "enum": [ "generate", "edit" ] }, "request": { "anyOf": [ { "$ref": "#/components/schemas/CreateIdea" }, { "type": "null" } ] } }, "required": [ "id", "variantId", "title", "description", "changes", "action", "request" ] }, "RecipeSummary": { "type": "object", "properties": { "variantId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "compromise": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "qualifiers": { "type": "array", "items": { "type": "string" } }, "name": { "type": "string" }, "batchMassG": { "type": "number" }, "status": { "const": "untested" }, "requiresAcceptance": { "type": "boolean" }, "carbonated": { "type": "boolean" }, "approach": { "type": "string" }, "ingredients": { "type": "array", "items": { "type": "object", "properties": { "ingredientId": { "type": "string" }, "name": { "type": "string" }, "sourceMassG": { "type": "number" }, "stockFraction": { "type": "number" }, "dispenseMassG": { "type": "number" }, "unit": { "const": "g" } }, "required": [ "ingredientId", "name", "sourceMassG", "stockFraction", "dispenseMassG", "unit" ] } }, "processSteps": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string", "description": "Concise intended sensory profile of the recipe; not a measured or tasted result." }, "quote": { "anyOf": [ { "$ref": "#/components/schemas/TestQuote" }, { "type": "null" } ] }, "quoteIssue": { "type": "object", "properties": { "code": { "const": "QUOTE_UNAVAILABLE" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "services": { "$ref": "#/components/schemas/ServiceOffer" } }, "required": [ "variantId", "compromise", "qualifiers", "name", "batchMassG", "status", "requiresAcceptance", "carbonated", "approach", "ingredients", "processSteps", "quote" ], "description": "Every returned candidate includes its customer quote in the recipe response. A numeric quote is a planning price, not permission to order or perform work: require services.review.eligible=true and current server-side physical qualification. Submission returns 422 PHYSICAL_QUALIFICATION_REQUIRED when that exact product/application qualification is missing or expired. For the customer service flow, display Test Trial for $XX using services.quote.totalCents. The recipe.quote covers the single-recipe kitchen package; services.quote includes selected variations and any estimated sample shipping. A lab report describes sample condition and characteristics, with photos, weighed recipe and maker aroma/flavor notes when performed. Instrument tests and shipment dispatch need separate approval. A service quote with totalCents:null is not orderable; show the unsupported scope and an alternative. quote:null plus quoteIssue means pricing failed without discarding the recipe. Retry order-quotes without regenerating. API/MCP candidates are ordered using source:idea, ideaId, ideaRevision and variantId, not their generation attempt ID." }, "Preparation": { "type": "object", "properties": { "steps": { "minItems": 1, "maxItems": 30, "type": "array", "items": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1500 }, { "oneOf": [ { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 1500 }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "const": "instruction" } }, "required": [ "instruction", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 1500 }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "const": "add" }, "ingredientId": { "type": "string", "minLength": 1, "maxLength": 100 }, "massG": { "type": "number", "exclusiveMinimum": 0, "maximum": 2000 } }, "required": [ "instruction", "type", "ingredientId" ], "additionalProperties": false }, { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 1500 }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "const": "mix" }, "temperatureC": { "type": "number", "minimum": 0, "maximum": 60 }, "durationSeconds": { "type": "integer", "minimum": 1, "maximum": 86400 } }, "required": [ "instruction", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 1500 }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "const": "chill" }, "temperatureC": { "type": "number", "minimum": 0, "maximum": 25 }, "durationSeconds": { "type": "integer", "minimum": 1, "maximum": 86400 } }, "required": [ "instruction", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 1500 }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "const": "carbonate" } }, "required": [ "instruction", "type" ], "additionalProperties": false } ] } ] } }, "notes": { "default": "", "type": "string", "maxLength": 2000 } }, "required": [ "steps" ], "additionalProperties": false, "description": "For source:ingredients orders only. Ordered text instructions or structured add/mix/chill/carbonate/instruction steps. If any step is an add, all recipe ingredients and specified or calculated water must be allocated exactly in aggregate; omitted massG uses the ingredient total. Step targets override bench defaults. Pure instructions use manual execution then record-only mass/lot reconciliation. See /exact-recipe-api.html." }, "BenchSettings": { "type": "object", "properties": { "balanceId": { "type": "string", "minLength": 1, "maxLength": 500 }, "minimumWeighableMassG": { "type": "number", "exclusiveMinimum": 0, "maximum": 2000 }, "vessel": { "type": "string", "minLength": 1, "maxLength": 500 }, "mixer": { "type": "string", "minLength": 1, "maxLength": 500 }, "temperatureC": { "type": "number", "minimum": 0, "maximum": 60 }, "mixingSeconds": { "type": "integer", "minimum": 1, "maximum": 3600 }, "mixingMethod": { "type": "string", "minLength": 1, "maxLength": 500 }, "temperatureToleranceC": { "type": "number", "minimum": 0, "maximum": 10 }, "massTolerancePercent": { "type": "number", "minimum": 0.1, "maximum": 10 }, "samplingMethod": { "type": "string", "minLength": 1, "maxLength": 500 }, "holdInstructions": { "type": "string", "minLength": 1, "maxLength": 500 }, "chillTemperatureC": { "default": null, "anyOf": [ { "type": "number", "minimum": 0, "maximum": 25 }, { "type": "null" } ] }, "chillSeconds": { "default": null, "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 86400 }, { "type": "null" } ] }, "chillMethod": { "default": "", "type": "string", "maxLength": 500 }, "carbonationEquipment": { "default": "", "type": "string", "maxLength": 500 }, "carbonationProcedure": { "default": "", "type": "string", "maxLength": 2000 } }, "required": [ "balanceId", "minimumWeighableMassG", "vessel", "mixer", "temperatureC", "mixingSeconds", "mixingMethod", "temperatureToleranceC", "massTolerancePercent", "samplingMethod", "holdInstructions" ], "additionalProperties": false }, "RecordStep": { "type": "object", "properties": { "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "batchId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "worksheetVersion": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "stepId": { "type": "string", "minLength": 1, "maxLength": 150 }, "confirmed": { "default": false, "type": "boolean" }, "correctionType": { "type": "string", "const": "clerical" }, "recoveredMassG": { "default": null, "anyOf": [ { "type": "number", "minimum": 0, "maximum": 5000 }, { "type": "null" } ] }, "actualLot": { "default": null, "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 150 }, { "type": "null" } ] }, "supersedesId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "correctionReason": { "type": "string", "minLength": 1, "maxLength": 500 }, "actualMassG": { "default": null, "anyOf": [ { "type": "number", "minimum": 0, "maximum": 5000 }, { "type": "null" } ] }, "temperatureC": { "default": null, "anyOf": [ { "type": "number", "minimum": -10, "maximum": 100 }, { "type": "null" } ] }, "durationSeconds": { "default": null, "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 86400 }, { "type": "null" } ] }, "note": { "default": "", "type": "string", "maxLength": 1000 } }, "required": [ "revision", "batchId", "worksheetVersion", "stepId" ], "additionalProperties": false }, "BenchStep": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "instruction": { "type": "string" }, "kind": { "enum": [ "setup", "addition", "mix", "chill", "carbonate", "instruction", "finish" ] }, "recordOnly": { "type": "boolean" }, "methodDetails": { "type": "string" }, "targetTemperatureC": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "targetDurationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "ingredientId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "targetMassG": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "requiredRecord": { "enum": [ "confirmation", "mass", "mix_conditions" ] } }, "required": [ "id", "title", "instruction", "kind", "ingredientId", "targetMassG", "requiredRecord" ] }, "StepRecord": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "batchId": { "type": "string", "format": "uuid" }, "stepId": { "type": "string" }, "worksheetVersion": { "type": "integer" }, "actualMassG": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "actualLot": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recoveredMassG": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "temperatureC": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "durationSeconds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "note": { "type": "string" }, "actor": { "type": "string" }, "recordedAt": { "type": "string", "format": "date-time" }, "supersedesId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "correctionReason": { "type": "string" } }, "required": [ "id", "batchId", "stepId", "worksheetVersion", "actualMassG", "actualLot", "recoveredMassG", "temperatureC", "durationSeconds", "note", "actor", "recordedAt", "supersedesId", "correctionReason" ] }, "Development": { "type": "object", "properties": { "approach": { "type": "string" }, "materials": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "ingredientId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quantity": { "type": "null" }, "status": { "type": "string" } }, "required": [ "name", "ingredientId", "quantity", "status" ] } }, "steps": { "type": "array", "items": { "type": "string" } }, "gaps": { "type": "array", "items": { "type": "string" } }, "benchmarks": { "type": "array", "items": { "type": "object", "properties": { "measure": { "type": "string" }, "target": { "type": "string" } }, "required": [ "measure", "target" ] } } }, "required": [ "approach", "materials", "steps", "gaps", "benchmarks" ] }, "Worksheet": { "type": "object", "properties": { "schemaVersion": { "const": "bench-worksheet-1" }, "version": { "type": "integer" }, "processLibraryVersion": { "type": "string" }, "kind": { "enum": [ "bench", "development" ] }, "settings": { "anyOf": [ { "$ref": "#/components/schemas/BenchSettings" }, { "type": "null" } ] }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/BenchStep" } }, "hash": { "type": "string" }, "reviewedHash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reviewedBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reviewedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/StepRecord" } }, "development": { "anyOf": [ { "$ref": "#/components/schemas/Development" }, { "type": "null" } ] } }, "required": [ "schemaVersion", "version", "processLibraryVersion", "kind", "settings", "steps", "hash", "reviewedHash", "reviewedBy", "reviewedAt", "records", "development" ] }, "WorksheetView": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid" }, "orderRevision": { "type": "integer" }, "status": { "type": "string" }, "name": { "type": "string" }, "batchMassG": { "type": "number" }, "replicates": { "type": "integer" }, "massBasis": { "type": "string" }, "ingredients": { "type": "array", "items": { "$ref": "#/components/schemas/ManifestLine" } }, "tests": { "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string" }, "min": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "metric", "min", "max" ] } }, "worksheet": { "anyOf": [ { "$ref": "#/components/schemas/Worksheet" }, { "type": "null" } ] }, "readiness": { "type": "object", "properties": { "ready": { "type": "boolean" }, "blockers": { "type": "array", "items": { "type": "string" } } }, "required": [ "ready", "blockers" ] }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "replicate": { "type": "integer" }, "completedSteps": { "type": "integer" }, "totalSteps": { "type": "integer" }, "nextStep": { "anyOf": [ { "$ref": "#/components/schemas/BenchStep" }, { "type": "null" } ] } }, "required": [ "id", "replicate", "completedSteps", "totalSteps", "nextStep" ] } }, "links": { "type": "object", "properties": { "self": { "type": "string" }, "workspace": { "type": "string" } }, "required": [ "self", "workspace" ] } }, "required": [ "orderId", "orderRevision", "status", "name", "batchMassG", "replicates", "massBasis", "ingredients", "tests", "worksheet", "readiness", "batches", "links" ] }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "requestId": { "type": "string", "format": "uuid" }, "details": {}, "resourceId": { "type": "string", "format": "uuid" } }, "required": [ "code", "message", "retryable", "requestId" ] } }, "required": [ "error" ] }, "CreateIdea": { "type": "object", "properties": { "prompt": { "type": "string", "minLength": 3, "maxLength": 1500 }, "kind": { "default": "beverage", "type": "string", "enum": [ "beverage", "flavor" ] }, "includeJuices": { "default": true, "type": "boolean" }, "batchMassG": { "default": 500, "type": "number", "minimum": 100, "maximum": 2000 }, "ingredientSelection": { "type": "object", "properties": { "availableIds": { "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "requiredIds": { "default": [], "maxItems": 8, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "required": [ "availableIds" ], "additionalProperties": false }, "constraints": { "type": "object", "properties": { "noAddedSweetener": { "type": "boolean" }, "excludedIngredientIds": { "maxItems": 166, "type": "array", "items": { "type": "string", "maxLength": 100 } }, "requiredAllergenExclusions": { "maxItems": 9, "type": "array", "items": { "type": "string", "enum": [ "milk", "egg", "fish", "crustacean_shellfish", "tree_nut", "peanut", "wheat", "soy", "sesame" ] } } }, "required": [ "noAddedSweetener", "excludedIngredientIds" ], "additionalProperties": false }, "variants": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }, "prompt": { "type": "string", "minLength": 3, "maxLength": 1500 } }, "required": [ "id", "prompt" ], "additionalProperties": false } } }, "required": [ "prompt" ], "additionalProperties": false, "description": "Prompt and batch mass plus optional exact ingredientSelection. Unknown IDs, explicit water/CO2, juice when includeJuices=false, and sweeteners in flavor mode are rejected. Known ingredients awaiting sourcing or dose qualification may be selected, but cannot enter a quantified recipe. Essential unavailable inputs yield recipes:[] with a concise reason and alternatives[]. The optional constraints object preserves noAddedSweetener and excludedIngredientIds as hard restrictions. A generate alternative contains a complete CreateIdea request: after agreement, submit it unchanged with a new key and generate the new idea. An edit alternative has request:null and requires an explicit constraint change; it is not a recipe. Unknown fields are rejected. Required IDs must be a subset of available IDs. Full details: /recipe-api.html." }, "CreateLabOrder": { "oneOf": [ { "type": "object", "properties": { "replicates": { "default": 1, "type": "integer", "minimum": 1, "maximum": 3 }, "tests": { "default": [ { "metric": "mass", "min": null, "max": null } ], "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "ph", "brix", "mass", "conductivity", "turbidity", "sensory" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] } }, "required": [ "metric", "min", "max" ], "additionalProperties": false } }, "source": { "type": "string", "const": "idea" }, "ideaId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ideaRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "acceptAlternative": { "default": false, "type": "boolean" }, "variantId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "source", "ideaId", "ideaRevision" ], "additionalProperties": false }, { "type": "object", "properties": { "replicates": { "default": 1, "type": "integer", "minimum": 1, "maximum": 3 }, "tests": { "default": [ { "metric": "mass", "min": null, "max": null } ], "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "ph", "brix", "mass", "conductivity", "turbidity", "sensory" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] } }, "required": [ "metric", "min", "max" ], "additionalProperties": false } }, "source": { "type": "string", "const": "generation" }, "generationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "acceptAlternative": { "default": false, "type": "boolean" }, "variantId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "source", "generationId" ], "additionalProperties": false }, { "type": "object", "properties": { "replicates": { "default": 1, "type": "integer", "minimum": 1, "maximum": 3 }, "tests": { "default": [ { "metric": "mass", "min": null, "max": null } ], "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "ph", "brix", "mass", "conductivity", "turbidity", "sensory" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] } }, "required": [ "metric", "min", "max" ], "additionalProperties": false } }, "source": { "type": "string", "const": "ingredients" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "catalogVersion": { "type": "string", "minLength": 1, "maxLength": 100 }, "batchMassG": { "type": "number", "minimum": 100, "maximum": 2000 }, "ingredients": { "minItems": 1, "maxItems": 21, "type": "array", "items": { "type": "object", "properties": { "ingredientId": { "type": "string", "minLength": 1, "maxLength": 100 }, "sourceMassG": { "type": "number", "exclusiveMinimum": 0, "maximum": 2000 } }, "required": [ "ingredientId", "sourceMassG" ], "additionalProperties": false } }, "carbonated": { "default": false, "type": "boolean" }, "allergenRequirements": { "maxItems": 9, "type": "array", "items": { "type": "string", "enum": [ "milk", "egg", "fish", "crustacean_shellfish", "tree_nut", "peanut", "wheat", "soy", "sesame" ] } }, "application": { "type": "string", "enum": [ "beverage", "water_flavor" ] }, "preparation": { "type": "object", "properties": { "steps": { "minItems": 1, "maxItems": 30, "type": "array", "items": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1500 }, { "oneOf": [ { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 1500 }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "const": "instruction" } }, "required": [ "instruction", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 1500 }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "const": "add" }, "ingredientId": { "type": "string", "minLength": 1, "maxLength": 100 }, "massG": { "type": "number", "exclusiveMinimum": 0, "maximum": 2000 } }, "required": [ "instruction", "type", "ingredientId" ], "additionalProperties": false }, { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 1500 }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "const": "mix" }, "temperatureC": { "type": "number", "minimum": 0, "maximum": 60 }, "durationSeconds": { "type": "integer", "minimum": 1, "maximum": 86400 } }, "required": [ "instruction", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 1500 }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "const": "chill" }, "temperatureC": { "type": "number", "minimum": 0, "maximum": 25 }, "durationSeconds": { "type": "integer", "minimum": 1, "maximum": 86400 } }, "required": [ "instruction", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 1500 }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "const": "carbonate" } }, "required": [ "instruction", "type" ], "additionalProperties": false } ] } ] } }, "notes": { "default": "", "type": "string", "maxLength": 2000 } }, "required": [ "steps" ], "additionalProperties": false }, "benchSettings": { "type": "object", "properties": { "balanceId": { "type": "string", "minLength": 1, "maxLength": 500 }, "minimumWeighableMassG": { "type": "number", "exclusiveMinimum": 0, "maximum": 2000 }, "vessel": { "type": "string", "minLength": 1, "maxLength": 500 }, "mixer": { "type": "string", "minLength": 1, "maxLength": 500 }, "temperatureC": { "type": "number", "minimum": 0, "maximum": 60 }, "mixingSeconds": { "type": "integer", "minimum": 1, "maximum": 3600 }, "mixingMethod": { "type": "string", "minLength": 1, "maxLength": 500 }, "temperatureToleranceC": { "type": "number", "minimum": 0, "maximum": 10 }, "massTolerancePercent": { "type": "number", "minimum": 0.1, "maximum": 10 }, "samplingMethod": { "type": "string", "minLength": 1, "maxLength": 500 }, "holdInstructions": { "type": "string", "minLength": 1, "maxLength": 500 }, "chillTemperatureC": { "default": null, "anyOf": [ { "type": "number", "minimum": 0, "maximum": 25 }, { "type": "null" } ] }, "chillSeconds": { "default": null, "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 86400 }, { "type": "null" } ] }, "chillMethod": { "default": "", "type": "string", "maxLength": 500 }, "carbonationEquipment": { "default": "", "type": "string", "maxLength": 500 }, "carbonationProcedure": { "default": "", "type": "string", "maxLength": 2000 } }, "required": [ "balanceId", "minimumWeighableMassG", "vessel", "mixer", "temperatureC", "mixingSeconds", "mixingMethod", "temperatureToleranceC", "massTolerancePercent", "samplingMethod", "holdInstructions" ], "additionalProperties": false } }, "required": [ "source", "name", "catalogVersion", "batchMassG", "ingredients" ], "additionalProperties": false } ], "description": "Additional cross-field and domain constraints are described in /api-guide.html; violations return422 or409 with a stable error code." }, "OrderAction": { "oneOf": [ { "type": "object", "properties": { "action": { "type": "string", "const": "configure" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "settings": { "type": "object", "properties": { "balanceId": { "type": "string", "minLength": 1, "maxLength": 500 }, "minimumWeighableMassG": { "type": "number", "exclusiveMinimum": 0, "maximum": 2000 }, "vessel": { "type": "string", "minLength": 1, "maxLength": 500 }, "mixer": { "type": "string", "minLength": 1, "maxLength": 500 }, "temperatureC": { "type": "number", "minimum": 0, "maximum": 60 }, "mixingSeconds": { "type": "integer", "minimum": 1, "maximum": 3600 }, "mixingMethod": { "type": "string", "minLength": 1, "maxLength": 500 }, "temperatureToleranceC": { "type": "number", "minimum": 0, "maximum": 10 }, "massTolerancePercent": { "type": "number", "minimum": 0.1, "maximum": 10 }, "samplingMethod": { "type": "string", "minLength": 1, "maxLength": 500 }, "holdInstructions": { "type": "string", "minLength": 1, "maxLength": 500 }, "chillTemperatureC": { "default": null, "anyOf": [ { "type": "number", "minimum": 0, "maximum": 25 }, { "type": "null" } ] }, "chillSeconds": { "default": null, "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 86400 }, { "type": "null" } ] }, "chillMethod": { "default": "", "type": "string", "maxLength": 500 }, "carbonationEquipment": { "default": "", "type": "string", "maxLength": 500 }, "carbonationProcedure": { "default": "", "type": "string", "maxLength": 2000 } }, "required": [ "balanceId", "minimumWeighableMassG", "vessel", "mixer", "temperatureC", "mixingSeconds", "mixingMethod", "temperatureToleranceC", "massTolerancePercent", "samplingMethod", "holdInstructions" ], "additionalProperties": false }, "tests": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "ph", "brix", "mass", "conductivity", "turbidity", "sensory" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] } }, "required": [ "metric", "min", "max" ], "additionalProperties": false } } }, "required": [ "action", "revision", "settings" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "accept" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "lots": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 150 } }, "process": { "type": "string", "minLength": 10, "maxLength": 4000 }, "note": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "action", "revision", "lots", "process", "note" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "start" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "action", "revision" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "abort" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "action", "revision", "reason" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "cancel" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "reason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "action", "revision", "reason" ], "additionalProperties": false } ], "description": "Additional cross-field and domain constraints are described in /api-guide.html; violations return422 or409 with a stable error code." }, "RecordResults": { "type": "object", "properties": { "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "measurements": { "default": [], "maxItems": 18, "type": "array", "items": { "type": "object", "properties": { "batchId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "metric": { "type": "string", "enum": [ "ph", "brix", "mass", "conductivity", "turbidity", "sensory" ] }, "value": { "type": "number" }, "unit": { "type": "string", "minLength": 1, "maxLength": 30 }, "method": { "type": "string", "minLength": 1, "maxLength": 500 }, "instrument": { "type": "string", "minLength": 1, "maxLength": 200 }, "calibration": { "type": "string", "minLength": 1, "maxLength": 500 }, "measuredAt": { "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))$" }, "supersedesId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "correctionReason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "batchId", "metric", "value", "unit", "method", "instrument", "calibration", "measuredAt" ], "additionalProperties": false } }, "preparations": { "default": [], "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "batchId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "lots": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 150 } }, "actualMasses": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number", "minimum": 0, "maximum": 5000 } }, "supersedesId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "correctionReason": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "batchId", "lots", "actualMasses" ], "additionalProperties": false } } }, "required": [ "revision" ], "additionalProperties": false, "description": "Additional cross-field and domain constraints are described in /api-guide.html; violations return422 or409 with a stable error code." }, "CreateApiKey": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "scopes": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "string", "enum": [ "ingredients:read", "ideas:read", "ideas:write", "orders:read", "orders:write", "lab:write" ] } }, "expiresInDays": { "default": 90, "type": "integer", "minimum": 1, "maximum": 365 } }, "required": [ "name", "scopes" ], "additionalProperties": false }, "Revision": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 1 } }, "required": [ "revision" ] }, "Idea": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "enum": [ "created", "running", "succeeded", "failed" ] }, "revision": { "type": "integer" }, "request": { "$ref": "#/components/schemas/CreateIdea" }, "catalogVersion": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recipes": { "type": "array", "items": { "$ref": "#/components/schemas/RecipeSummary" } }, "alternatives": { "type": "array", "items": { "$ref": "#/components/schemas/RecipeAlternative" } }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gaps": { "type": "array", "items": { "$ref": "#/components/schemas/RecipeGap" } }, "requestedCount": { "type": "integer" }, "returnedCount": { "type": "integer" }, "recipe": { "anyOf": [ { "$ref": "#/components/schemas/RecipeSummary" }, { "type": "null" } ] }, "stage": { "anyOf": [ { "enum": [ "explore", "improve", "finalize" ] }, { "type": "null" } ] }, "result": { "anyOf": [ { "$ref": "#/components/schemas/Suggestion" }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "message", "retryable" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "links": { "type": "object", "properties": { "self": { "type": "string" }, "generate": { "type": "string" } }, "required": [ "self", "generate" ] } }, "required": [ "id", "status", "revision", "request", "recipes", "alternatives", "reason", "gaps", "requestedCount", "returnedCount", "stage", "result", "error", "createdAt", "updatedAt", "links" ] }, "Suggestion": { "type": "object", "properties": { "recipes": { "type": "array", "items": { "$ref": "#/components/schemas/RecipeSummary" } }, "alternatives": { "type": "array", "items": { "$ref": "#/components/schemas/RecipeAlternative" } }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gaps": { "type": "array", "items": { "$ref": "#/components/schemas/RecipeGap" } }, "requestedCount": { "type": "integer" }, "returnedCount": { "type": "integer" }, "request": { "$ref": "#/components/schemas/CreateIdea" }, "brief": { "type": "object", "properties": { "name": { "type": "string" }, "batchMassG": { "type": "number" }, "carbonated": { "type": "boolean" }, "studio": { "type": "object", "properties": { "ai": { "type": "object", "properties": { "model": { "type": "string" }, "ingredientLibraryVersion": { "type": "string" }, "requestScope": { "enum": [ "beverage", "water_flavor", "outside_scope" ] }, "extendedIngredientIds": { "type": "array", "items": { "type": "string" } }, "fulfillment": { "type": "object", "properties": { "status": { "enum": [ "supported", "alternative", "development_required", "unsupported" ] }, "approach": { "type": "string" }, "reason": { "type": "string" }, "compromise": { "type": "string" }, "processes": { "type": "array", "items": { "type": "string" } } }, "required": [ "status", "approach", "reason", "compromise", "processes" ] } }, "required": [ "fulfillment" ] } }, "required": [ "ai" ] } }, "required": [ "name", "batchMassG", "studio" ] }, "recipe": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "ingredientId": { "type": "string" }, "sourceMassG": { "type": "number" }, "stockFraction": { "type": "number" } }, "required": [ "ingredientId", "sourceMassG", "stockFraction" ] } } }, "required": [ "id", "name", "lines" ] }, { "type": "null" } ] }, "notes": { "type": "array", "items": { "type": "string" } }, "unmatched": { "type": "array", "items": { "type": "string" } }, "recognized": { "type": "array", "items": { "type": "string" } }, "engine": { "type": "string" } }, "required": [ "recipes", "alternatives", "reason", "gaps", "requestedCount", "returnedCount", "request", "brief", "recipe", "notes", "unmatched", "recognized", "engine" ] }, "LaunchBank": { "type": "object", "properties": { "gaps": { "type": "array", "items": { "type": "string" } }, "count": { "type": "integer" } }, "required": [ "gaps", "count" ] }, "LabScope": { "type": "object", "properties": { "version": { "type": "string" }, "formats": { "type": "array", "items": { "type": "string" } }, "supportedProcesses": { "type": "array", "items": { "type": "string" } }, "developmentProcesses": { "type": "array", "items": { "type": "string" } }, "outsideScope": { "type": "array", "items": { "type": "string" } }, "examples": { "type": "object" }, "inventoryStatus": { "type": "string" }, "testingStatus": { "type": "string" } }, "required": [ "version", "formats", "supportedProcesses", "developmentProcesses", "outsideScope", "examples", "inventoryStatus", "testingStatus" ] }, "Ingredient": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "summary": { "type": "string" }, "flavorFamily": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "sensoryTags": { "type": "array", "items": { "type": "string" } }, "suggestedPairings": { "type": "array", "items": { "type": "string" } }, "creativeApplications": { "type": "array", "items": { "type": "string" } }, "containsAddedSweetener": { "type": "boolean", "description": "True when the ingredient profile documents an added sweetener. Missing does not establish a sugar-free claim." }, "draftEligible": { "type": "boolean" }, "technical": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "value": { "type": "string" } }, "required": [ "field", "value" ] } }, "version": { "type": "string" } }, "required": [ "id", "name", "category", "summary", "draftEligible", "technical", "version" ], "description": "Basic catalog profile with available composition, carrier, allergen, solubility and appearance details. Missing information does not establish suitability, physical inventory or an approved dose. Sourcing records remain private to the lab." }, "Metric": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "unit": { "type": "string" }, "min": { "type": "number" }, "max": { "type": "number" }, "method": { "type": "string" } }, "required": [ "id", "name", "unit", "min", "max", "method" ] }, "ManifestLine": { "type": "object", "properties": { "ingredientId": { "type": "string" }, "name": { "type": "string" }, "sourceMassG": { "type": "number" }, "totalMassG": { "type": "number" }, "technical": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "value": { "type": "string" } }, "required": [ "field", "value" ] } }, "unknowns": { "type": "array", "items": { "type": "string" } } }, "required": [ "ingredientId", "name", "sourceMassG", "totalMassG" ] }, "LabOrder": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "enum": [ "pending_review", "accepted", "testing", "completed", "cancelled", "aborted" ] }, "revision": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "catalogVersion": { "type": "string" }, "formulaHash": { "type": "string" }, "preparation": { "$ref": "#/components/schemas/Preparation" }, "generationId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "worksheet": { "$ref": "#/components/schemas/Worksheet" }, "ideaId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "ideaRevision": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "batchMassG": { "type": "number" }, "replicates": { "type": "integer" }, "ingredients": { "type": "array", "items": { "$ref": "#/components/schemas/ManifestLine" } }, "process": { "type": "object", "properties": { "carbonated": { "type": "boolean" }, "steps": { "type": "array", "items": { "type": "string" } }, "operations": { "type": "array", "items": { "type": "string" } } }, "required": [ "carbonated", "steps", "operations" ] }, "tests": { "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string" }, "min": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "metric", "min", "max" ] } }, "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "replicate": { "type": "integer" } }, "required": [ "id", "replicate" ] } }, "qualification": { "anyOf": [ { "type": "object", "additionalProperties": true }, { "type": "null" } ] }, "preparations": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "measurements": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "history": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string" }, "actor": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "note": { "type": "string" } }, "required": [ "action", "actor", "at", "note" ] } }, "fulfillment": { "type": "object", "properties": { "type": { "const": "lab_work_order" }, "dispatch": { "const": "not_connected" }, "provisional": { "const": true } }, "required": [ "type", "dispatch", "provisional" ] }, "pricing": { "$ref": "#/components/schemas/TestQuote" }, "pricingReviewRequired": { "type": "boolean" } }, "required": [ "id", "name", "status", "revision", "createdAt", "updatedAt", "catalogVersion", "formulaHash", "generationId", "worksheet", "ideaId", "ideaRevision", "batchMassG", "replicates", "ingredients", "process", "tests", "batches", "qualification", "preparations", "measurements", "history", "fulfillment" ] }, "Evaluation": { "type": "object", "properties": { "status": { "enum": [ "incomplete", "passed", "failed", "recorded" ] }, "execution": { "type": "object", "properties": { "status": { "type": "string" }, "missingSteps": { "type": "integer" }, "deviations": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "required": [ "status", "missingSteps", "deviations" ] }, "missingMeasurements": { "type": "integer" }, "missingPreparations": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "cells": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "preparationDifferences": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "lotDifferences": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "recipeConformance": { "enum": [ "deviations_recorded", "not_recorded", "matches_recorded_masses" ] }, "evidence": { "type": "string" } }, "required": [ "status", "execution", "missingMeasurements", "missingPreparations", "cells", "preparationDifferences", "lotDifferences", "recipeConformance", "evidence" ] }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "type": "string", "format": "date-time" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "name", "prefix", "scopes", "expiresAt", "createdAt" ] }, "SubmitRequest": { "type": "object", "properties": { "source": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "prompt" }, "prompt": { "type": "string", "minLength": 3, "maxLength": 1500 } }, "required": [ "type", "prompt" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "generation" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "idea" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "order" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "type", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "experiment" }, "plan": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "experiment-2026-10-01-v1" }, "physicalSamples": { "type": "object", "properties": { "requested": { "type": "boolean" }, "notes": { "type": "string", "maxLength": 500 } }, "required": [ "requested", "notes" ], "additionalProperties": false }, "groups": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 3, "maxLength": 100 }, "objective": { "type": "string", "minLength": 3, "maxLength": 1200 }, "operation": { "type": "string", "enum": [ "ambient_aqueous_mix", "custom_review" ] }, "materialFamily": { "type": "string", "minLength": 3, "maxLength": 300 }, "protocol": { "type": "string", "minLength": 3, "maxLength": 600 }, "protocolVersion": { "type": "string", "minLength": 1, "maxLength": 50 }, "sharedBatchClaim": { "type": "boolean" }, "measurements": { "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "ph", "brix", "mass" ] } }, "extras": { "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "shipping", "custom_ingredients", "specialized_assays", "extended_stability", "complex_operation" ] } }, "formulations": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 3, "maxLength": 100 }, "role": { "type": "string", "enum": [ "sample", "control", "repeat" ] }, "description": { "type": "string", "minLength": 3, "maxLength": 500 }, "preparationCount": { "type": "integer", "minimum": 1, "maximum": 12 }, "repeatOf": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "id", "name", "role", "description", "preparationCount" ], "additionalProperties": false } } }, "required": [ "id", "name", "objective", "operation", "materialFamily", "protocol", "protocolVersion", "sharedBatchClaim", "measurements", "extras", "formulations" ], "additionalProperties": false } }, "parentRequest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "change": { "type": "string", "minLength": 3, "maxLength": 1000 } }, "required": [ "id", "revision", "change" ], "additionalProperties": false } }, "required": [ "schemaVersion", "physicalSamples", "groups" ], "additionalProperties": false }, "quoteHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "type", "plan", "quoteHash" ], "additionalProperties": false } ] }, "notes": { "default": "", "type": "string", "maxLength": 2000 }, "shareWithTeam": { "type": "boolean", "const": true }, "contactAllowed": { "default": false, "type": "boolean" }, "contactEmail": { "type": "string", "maxLength": 254, "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,}$" } }, "required": [ "source", "shareWithTeam" ], "additionalProperties": false }, "RequestSubmission": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "prompt": { "type": "string" }, "source": { "type": "object" }, "snapshot": { "description": "Frozen submitted scope. A service-order snapshot may include public quoted-order checkout consent; internal identity/audit details are never returned.", "properties": { "checkout": { "$ref": "#/components/schemas/QuotedOrderCheckout" } } }, "notes": { "type": "string" }, "status": { "enum": [ "new", "reviewed", "closed", "withdrawn" ] }, "revision": { "type": "integer" }, "contactAllowed": { "type": "boolean" }, "contactEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "consentVersion": { "type": "string" }, "consentedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "notice": { "type": "string" }, "orderStatus": { "$ref": "#/components/schemas/ServiceOrderStatus" }, "payment": { "$ref": "#/components/schemas/TestPayment" } }, "description": "An owned submission. POST /orders with checkout:{acceptQuote:true} initializes pending payment for a complete supported quote in test or stripe_test mode and returns public snapshot.checkout. Omitting checkout saves a supported priced record awaiting_checkout, with no payment or inferred consent. Explicit saved-quote acceptance at /orders/{id}/checkout initializes pending payment. Private checkout consent identity/audit data is omitted. Older legacy records may contain unbound simulations." }, "RequestStatus": { "type": "object", "properties": { "revision": { "type": "integer", "minimum": 1 }, "status": { "enum": [ "reviewed", "closed", "withdrawn" ] } }, "required": [ "revision", "status" ], "additionalProperties": false }, "ExperimentPlan": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "experiment-2026-10-01-v1" }, "physicalSamples": { "type": "object", "properties": { "requested": { "type": "boolean" }, "notes": { "type": "string", "maxLength": 500 } }, "required": [ "requested", "notes" ], "additionalProperties": false }, "groups": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 3, "maxLength": 100 }, "objective": { "type": "string", "minLength": 3, "maxLength": 1200 }, "operation": { "type": "string", "enum": [ "ambient_aqueous_mix", "custom_review" ] }, "materialFamily": { "type": "string", "minLength": 3, "maxLength": 300 }, "protocol": { "type": "string", "minLength": 3, "maxLength": 600 }, "protocolVersion": { "type": "string", "minLength": 1, "maxLength": 50 }, "sharedBatchClaim": { "type": "boolean" }, "measurements": { "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "ph", "brix", "mass" ] } }, "extras": { "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "shipping", "custom_ingredients", "specialized_assays", "extended_stability", "complex_operation" ] } }, "formulations": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 3, "maxLength": 100 }, "role": { "type": "string", "enum": [ "sample", "control", "repeat" ] }, "description": { "type": "string", "minLength": 3, "maxLength": 500 }, "preparationCount": { "type": "integer", "minimum": 1, "maximum": 12 }, "repeatOf": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "id", "name", "role", "description", "preparationCount" ], "additionalProperties": false } } }, "required": [ "id", "name", "objective", "operation", "materialFamily", "protocol", "protocolVersion", "sharedBatchClaim", "measurements", "extras", "formulations" ], "additionalProperties": false } }, "parentRequest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "change": { "type": "string", "minLength": 3, "maxLength": 1000 } }, "required": [ "id", "revision", "change" ], "additionalProperties": false } }, "required": [ "schemaVersion", "physicalSamples", "groups" ], "additionalProperties": false }, "QuoteExperiment": { "type": "object", "properties": { "plan": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "experiment-2026-10-01-v1" }, "physicalSamples": { "type": "object", "properties": { "requested": { "type": "boolean" }, "notes": { "type": "string", "maxLength": 500 } }, "required": [ "requested", "notes" ], "additionalProperties": false }, "groups": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 3, "maxLength": 100 }, "objective": { "type": "string", "minLength": 3, "maxLength": 1200 }, "operation": { "type": "string", "enum": [ "ambient_aqueous_mix", "custom_review" ] }, "materialFamily": { "type": "string", "minLength": 3, "maxLength": 300 }, "protocol": { "type": "string", "minLength": 3, "maxLength": 600 }, "protocolVersion": { "type": "string", "minLength": 1, "maxLength": 50 }, "sharedBatchClaim": { "type": "boolean" }, "measurements": { "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "ph", "brix", "mass" ] } }, "extras": { "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "shipping", "custom_ingredients", "specialized_assays", "extended_stability", "complex_operation" ] } }, "formulations": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 3, "maxLength": 100 }, "role": { "type": "string", "enum": [ "sample", "control", "repeat" ] }, "description": { "type": "string", "minLength": 3, "maxLength": 500 }, "preparationCount": { "type": "integer", "minimum": 1, "maximum": 12 }, "repeatOf": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "id", "name", "role", "description", "preparationCount" ], "additionalProperties": false } } }, "required": [ "id", "name", "objective", "operation", "materialFamily", "protocol", "protocolVersion", "sharedBatchClaim", "measurements", "extras", "formulations" ], "additionalProperties": false } }, "parentRequest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "change": { "type": "string", "minLength": 3, "maxLength": 1000 } }, "required": [ "id", "revision", "change" ], "additionalProperties": false } }, "required": [ "schemaVersion", "physicalSamples", "groups" ], "additionalProperties": false } }, "required": [ "plan" ], "additionalProperties": false }, "CreateExperiment": { "type": "object", "properties": { "plan": { "type": "object", "properties": { "schemaVersion": { "type": "string", "const": "experiment-2026-10-01-v1" }, "physicalSamples": { "type": "object", "properties": { "requested": { "type": "boolean" }, "notes": { "type": "string", "maxLength": 500 } }, "required": [ "requested", "notes" ], "additionalProperties": false }, "groups": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 3, "maxLength": 100 }, "objective": { "type": "string", "minLength": 3, "maxLength": 1200 }, "operation": { "type": "string", "enum": [ "ambient_aqueous_mix", "custom_review" ] }, "materialFamily": { "type": "string", "minLength": 3, "maxLength": 300 }, "protocol": { "type": "string", "minLength": 3, "maxLength": 600 }, "protocolVersion": { "type": "string", "minLength": 1, "maxLength": 50 }, "sharedBatchClaim": { "type": "boolean" }, "measurements": { "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "ph", "brix", "mass" ] } }, "extras": { "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "shipping", "custom_ingredients", "specialized_assays", "extended_stability", "complex_operation" ] } }, "formulations": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "name": { "type": "string", "minLength": 3, "maxLength": 100 }, "role": { "type": "string", "enum": [ "sample", "control", "repeat" ] }, "description": { "type": "string", "minLength": 3, "maxLength": 500 }, "preparationCount": { "type": "integer", "minimum": 1, "maximum": 12 }, "repeatOf": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "id", "name", "role", "description", "preparationCount" ], "additionalProperties": false } } }, "required": [ "id", "name", "objective", "operation", "materialFamily", "protocol", "protocolVersion", "sharedBatchClaim", "measurements", "extras", "formulations" ], "additionalProperties": false } }, "parentRequest": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "change": { "type": "string", "minLength": 3, "maxLength": 1000 } }, "required": [ "id", "revision", "change" ], "additionalProperties": false } }, "required": [ "schemaVersion", "physicalSamples", "groups" ], "additionalProperties": false }, "quoteHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "notes": { "default": "", "type": "string", "maxLength": 2000 }, "shareWithTeam": { "type": "boolean", "const": true }, "contactAllowed": { "default": false, "type": "boolean" }, "contactEmail": { "type": "string", "maxLength": 254, "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,}$" } }, "required": [ "plan", "quoteHash", "shareWithTeam" ], "additionalProperties": false }, "LinkExperimentEvidence": { "type": "object", "properties": { "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "groupId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "formulationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "replicate": { "type": "integer", "minimum": 1, "maximum": 12 }, "orderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "orderRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "batchId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "scopeConfirmed": { "type": "boolean", "const": true }, "scopeNote": { "type": "string", "minLength": 10, "maxLength": 1000 } }, "required": [ "revision", "groupId", "formulationId", "replicate", "orderId", "orderRevision", "batchId", "scopeConfirmed", "scopeNote" ], "additionalProperties": false }, "ExperimentQuote": { "type": "object", "properties": { "scopeHash": { "type": "string" }, "status": { "const": "planning_only" }, "binding": { "const": false }, "currency": { "const": "USD" }, "totalCents": { "type": "null" }, "quoteRequired": { "const": false }, "groups": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "count": { "type": "integer" }, "counts": { "type": "object", "properties": { "sample": { "type": "integer" }, "control": { "type": "integer" }, "repeat": { "type": "integer" } }, "required": [ "sample", "control", "repeat" ] }, "cents": { "type": "null" }, "status": { "const": "planning_only" }, "qualification": { "const": "not_quoted" } }, "required": [ "groupId", "name", "count", "counts", "cents", "status", "qualification" ] } }, "physicalSamples": { "type": "object", "properties": { "requested": { "type": "boolean" }, "status": { "enum": [ "not_offered", "not_requested" ] }, "costCents": { "type": "null" } }, "required": [ "requested", "status", "costCents" ] }, "notice": { "type": "string" }, "exclusions": { "type": "string" } }, "required": [ "scopeHash", "status", "binding", "currency", "totalCents", "quoteRequired", "groups", "physicalSamples", "notice", "exclusions" ], "description": "Validated, unpriced planning scope. Free-text descriptions never establish ingredient availability or an executable recipe and receive no price or custom-quote promise. Historical planning estimates are also projected as unpriced; stored history is retained privately. Generate a supported catalog recipe and use /order-quotes and /orders for an actual purchase." }, "ExperimentResults": { "type": "object", "properties": { "status": { "enum": [ "not_performed", "incomplete", "completed", "withdrawn" ] }, "samples": { "type": "array", "items": { "type": "object", "properties": { "sampleId": { "type": "string" }, "groupId": { "type": "string", "format": "uuid" }, "formulationId": { "type": "string", "format": "uuid" }, "replicate": { "type": "integer" }, "status": { "enum": [ "not_performed", "incomplete", "completed" ] }, "protocol": { "type": "object" }, "measurements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "batchId": { "type": "string", "format": "uuid" }, "metric": { "type": "string" }, "value": { "type": "number" }, "unit": { "type": "string" }, "method": { "type": "string" }, "instrument": { "type": "string" }, "calibration": { "type": "string" }, "measuredAt": { "type": "string", "format": "date-time" }, "recordedAt": { "type": "string", "format": "date-time" }, "targetCheck": { "type": "string" } } } }, "evidenceLinks": { "type": "array", "items": { "type": "object" } }, "limitations": { "type": "array", "items": { "type": "string" } } } } }, "measurements": { "type": "array", "items": { "type": "object" } }, "evidenceLinks": { "type": "array", "items": { "type": "object" } }, "limitations": { "type": "array", "items": { "type": "string" } } }, "required": [ "status", "samples", "measurements", "evidenceLinks", "limitations" ] }, "Experiment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "revision": { "type": "integer" }, "state": { "enum": [ "planned", "in_progress", "completed", "closed", "withdrawn" ] }, "reviewStatus": { "enum": [ "new", "reviewed", "closed", "withdrawn" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "plan": { "anyOf": [ { "$ref": "#/components/schemas/ExperimentPlan" }, { "type": "null" } ] }, "quote": { "anyOf": [ { "$ref": "#/components/schemas/ExperimentQuote" }, { "type": "null" } ] }, "results": { "$ref": "#/components/schemas/ExperimentResults" }, "links": { "type": "object" } }, "required": [ "id", "revision", "state", "reviewStatus", "createdAt", "updatedAt", "plan", "quote", "results", "links" ] }, "TestQuote": { "type": "object", "properties": { "scopeHash": { "type": "string" }, "currency": { "const": "USD" }, "binding": { "const": false }, "status": { "enum": [ "provisional", "quote_required" ] }, "totalCents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "scope": { "type": "object", "properties": { "batchMassG": { "type": "number" }, "preparations": { "type": "integer" }, "ingredientCount": { "type": "integer" }, "measurements": { "type": "array", "items": { "type": "string" } } }, "required": [ "batchMassG", "preparations", "ingredientCount", "measurements" ] }, "includes": { "type": "array", "items": { "type": "string" } }, "exclusions": { "type": "array", "items": { "type": "string" } }, "reviewNotes": { "type": "array", "items": { "type": "string" } }, "notice": { "type": "string" } }, "required": [ "scopeHash", "currency", "binding", "status", "totalCents", "scope", "includes", "exclusions", "notice" ], "description": "Customer quote for a recipe test. The exact ingredients, quantities and preparation determine the price. Show the returned estimated USD total, scope, inclusions, exclusions and reviewNotes; never calculate the price in the client. Review notes preserve equipment and ingredient-cost confirmation without hiding a supported service price. A null total requires a custom quote, never a free test. The scopeHash identifies the exact quote to submit as quoteHash." }, "QuoteRecipeTest": { "type": "object", "properties": { "generationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "acceptAlternative": { "default": false, "type": "boolean" }, "variantId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "generationId" ], "additionalProperties": false }, "Checkout": { "type": "object", "properties": { "generationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "acceptAlternative": { "default": false, "type": "boolean" }, "variantId": { "type": "string", "minLength": 1, "maxLength": 64 }, "shareWithTeam": { "type": "boolean", "const": true }, "quoteHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "generationId", "shareWithTeam" ], "additionalProperties": false }, "CheckoutReceipt": { "type": "object", "properties": { "order": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string" }, "batchMassG": { "type": "number" }, "createdAt": { "type": "string", "format": "date-time" }, "pricing": { "anyOf": [ { "$ref": "#/components/schemas/TestQuote" }, { "type": "null" } ] }, "pricingReviewRequired": { "type": "boolean" } }, "required": [ "id", "name", "status", "batchMassG", "createdAt", "pricing", "pricingReviewRequired" ] }, "submission": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" } }, "required": [ "id", "status" ] }, "notice": { "type": "string" } }, "required": [ "order", "submission", "notice" ] }, "QuoteOrder": { "type": "object", "properties": { "recipe": { "oneOf": [ { "type": "object", "properties": { "replicates": { "default": 1, "type": "integer", "minimum": 1, "maximum": 3 }, "tests": { "default": [ { "metric": "mass", "min": null, "max": null } ], "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "ph", "brix", "mass", "conductivity", "turbidity", "sensory" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] } }, "required": [ "metric", "min", "max" ], "additionalProperties": false } }, "source": { "type": "string", "const": "idea" }, "ideaId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ideaRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "acceptAlternative": { "default": false, "type": "boolean" }, "variantId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "source", "ideaId", "ideaRevision" ], "additionalProperties": false }, { "type": "object", "properties": { "replicates": { "default": 1, "type": "integer", "minimum": 1, "maximum": 3 }, "tests": { "default": [ { "metric": "mass", "min": null, "max": null } ], "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "ph", "brix", "mass", "conductivity", "turbidity", "sensory" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] } }, "required": [ "metric", "min", "max" ], "additionalProperties": false } }, "source": { "type": "string", "const": "generation" }, "generationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "acceptAlternative": { "default": false, "type": "boolean" }, "variantId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "source", "generationId" ], "additionalProperties": false }, { "type": "object", "properties": { "replicates": { "default": 1, "type": "integer", "minimum": 1, "maximum": 3 }, "tests": { "default": [ { "metric": "mass", "min": null, "max": null } ], "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "ph", "brix", "mass", "conductivity", "turbidity", "sensory" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] } }, "required": [ "metric", "min", "max" ], "additionalProperties": false } }, "source": { "type": "string", "const": "ingredients" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "catalogVersion": { "type": "string", "minLength": 1, "maxLength": 100 }, "batchMassG": { "type": "number", "minimum": 100, "maximum": 2000 }, "ingredients": { "minItems": 1, "maxItems": 21, "type": "array", "items": { "type": "object", "properties": { "ingredientId": { "type": "string", "minLength": 1, "maxLength": 100 }, "sourceMassG": { "type": "number", "exclusiveMinimum": 0, "maximum": 2000 } }, "required": [ "ingredientId", "sourceMassG" ], "additionalProperties": false } }, "carbonated": { "default": false, "type": "boolean" }, "allergenRequirements": { "maxItems": 9, "type": "array", "items": { "type": "string", "enum": [ "milk", "egg", "fish", "crustacean_shellfish", "tree_nut", "peanut", "wheat", "soy", "sesame" ] } }, "application": { "type": "string", "enum": [ "beverage", "water_flavor" ] }, "preparation": { "type": "object", "properties": { "steps": { "minItems": 1, "maxItems": 30, "type": "array", "items": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1500 }, { "oneOf": [ { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 1500 }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "const": "instruction" } }, "required": [ "instruction", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 1500 }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "const": "add" }, "ingredientId": { "type": "string", "minLength": 1, "maxLength": 100 }, "massG": { "type": "number", "exclusiveMinimum": 0, "maximum": 2000 } }, "required": [ "instruction", "type", "ingredientId" ], "additionalProperties": false }, { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 1500 }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "const": "mix" }, "temperatureC": { "type": "number", "minimum": 0, "maximum": 60 }, "durationSeconds": { "type": "integer", "minimum": 1, "maximum": 86400 } }, "required": [ "instruction", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 1500 }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "const": "chill" }, "temperatureC": { "type": "number", "minimum": 0, "maximum": 25 }, "durationSeconds": { "type": "integer", "minimum": 1, "maximum": 86400 } }, "required": [ "instruction", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 1500 }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "const": "carbonate" } }, "required": [ "instruction", "type" ], "additionalProperties": false } ] } ] } }, "notes": { "default": "", "type": "string", "maxLength": 2000 } }, "required": [ "steps" ], "additionalProperties": false }, "benchSettings": { "type": "object", "properties": { "balanceId": { "type": "string", "minLength": 1, "maxLength": 500 }, "minimumWeighableMassG": { "type": "number", "exclusiveMinimum": 0, "maximum": 2000 }, "vessel": { "type": "string", "minLength": 1, "maxLength": 500 }, "mixer": { "type": "string", "minLength": 1, "maxLength": 500 }, "temperatureC": { "type": "number", "minimum": 0, "maximum": 60 }, "mixingSeconds": { "type": "integer", "minimum": 1, "maximum": 3600 }, "mixingMethod": { "type": "string", "minLength": 1, "maxLength": 500 }, "temperatureToleranceC": { "type": "number", "minimum": 0, "maximum": 10 }, "massTolerancePercent": { "type": "number", "minimum": 0.1, "maximum": 10 }, "samplingMethod": { "type": "string", "minLength": 1, "maxLength": 500 }, "holdInstructions": { "type": "string", "minLength": 1, "maxLength": 500 }, "chillTemperatureC": { "default": null, "anyOf": [ { "type": "number", "minimum": 0, "maximum": 25 }, { "type": "null" } ] }, "chillSeconds": { "default": null, "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 86400 }, { "type": "null" } ] }, "chillMethod": { "default": "", "type": "string", "maxLength": 500 }, "carbonationEquipment": { "default": "", "type": "string", "maxLength": 500 }, "carbonationProcedure": { "default": "", "type": "string", "maxLength": 2000 } }, "required": [ "balanceId", "minimumWeighableMassG", "vessel", "mixer", "temperatureC", "mixingSeconds", "mixingMethod", "temperatureToleranceC", "massTolerancePercent", "samplingMethod", "holdInstructions" ], "additionalProperties": false } }, "required": [ "source", "name", "catalogVersion", "batchMassG", "ingredients" ], "additionalProperties": false } ] }, "deliverables": { "default": [ "photo", "taste" ], "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "photo", "taste", "ship" ] } }, "variationIds": { "default": [], "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "reduced_20", "reduced_40" ] } }, "destination": { "type": "object", "properties": { "country": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "region": { "type": "string", "minLength": 2, "maxLength": 100 }, "postalCode": { "type": "string", "minLength": 3, "maxLength": 20 } }, "required": [ "country", "region", "postalCode" ], "additionalProperties": false } }, "required": [ "recipe" ], "additionalProperties": false }, "PlaceOrder": { "type": "object", "properties": { "selection": { "type": "object", "properties": { "recipe": { "oneOf": [ { "type": "object", "properties": { "replicates": { "default": 1, "type": "integer", "minimum": 1, "maximum": 3 }, "tests": { "default": [ { "metric": "mass", "min": null, "max": null } ], "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "ph", "brix", "mass", "conductivity", "turbidity", "sensory" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] } }, "required": [ "metric", "min", "max" ], "additionalProperties": false } }, "source": { "type": "string", "const": "idea" }, "ideaId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ideaRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "acceptAlternative": { "default": false, "type": "boolean" }, "variantId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "source", "ideaId", "ideaRevision" ], "additionalProperties": false }, { "type": "object", "properties": { "replicates": { "default": 1, "type": "integer", "minimum": 1, "maximum": 3 }, "tests": { "default": [ { "metric": "mass", "min": null, "max": null } ], "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "ph", "brix", "mass", "conductivity", "turbidity", "sensory" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] } }, "required": [ "metric", "min", "max" ], "additionalProperties": false } }, "source": { "type": "string", "const": "generation" }, "generationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "acceptAlternative": { "default": false, "type": "boolean" }, "variantId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "source", "generationId" ], "additionalProperties": false }, { "type": "object", "properties": { "replicates": { "default": 1, "type": "integer", "minimum": 1, "maximum": 3 }, "tests": { "default": [ { "metric": "mass", "min": null, "max": null } ], "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "ph", "brix", "mass", "conductivity", "turbidity", "sensory" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] } }, "required": [ "metric", "min", "max" ], "additionalProperties": false } }, "source": { "type": "string", "const": "ingredients" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "catalogVersion": { "type": "string", "minLength": 1, "maxLength": 100 }, "batchMassG": { "type": "number", "minimum": 100, "maximum": 2000 }, "ingredients": { "minItems": 1, "maxItems": 21, "type": "array", "items": { "type": "object", "properties": { "ingredientId": { "type": "string", "minLength": 1, "maxLength": 100 }, "sourceMassG": { "type": "number", "exclusiveMinimum": 0, "maximum": 2000 } }, "required": [ "ingredientId", "sourceMassG" ], "additionalProperties": false } }, "carbonated": { "default": false, "type": "boolean" }, "allergenRequirements": { "maxItems": 9, "type": "array", "items": { "type": "string", "enum": [ "milk", "egg", "fish", "crustacean_shellfish", "tree_nut", "peanut", "wheat", "soy", "sesame" ] } }, "application": { "type": "string", "enum": [ "beverage", "water_flavor" ] }, "preparation": { "type": "object", "properties": { "steps": { "minItems": 1, "maxItems": 30, "type": "array", "items": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1500 }, { "oneOf": [ { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 1500 }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "const": "instruction" } }, "required": [ "instruction", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 1500 }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "const": "add" }, "ingredientId": { "type": "string", "minLength": 1, "maxLength": 100 }, "massG": { "type": "number", "exclusiveMinimum": 0, "maximum": 2000 } }, "required": [ "instruction", "type", "ingredientId" ], "additionalProperties": false }, { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 1500 }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "const": "mix" }, "temperatureC": { "type": "number", "minimum": 0, "maximum": 60 }, "durationSeconds": { "type": "integer", "minimum": 1, "maximum": 86400 } }, "required": [ "instruction", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 1500 }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "const": "chill" }, "temperatureC": { "type": "number", "minimum": 0, "maximum": 25 }, "durationSeconds": { "type": "integer", "minimum": 1, "maximum": 86400 } }, "required": [ "instruction", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 1500 }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "const": "carbonate" } }, "required": [ "instruction", "type" ], "additionalProperties": false } ] } ] } }, "notes": { "default": "", "type": "string", "maxLength": 2000 } }, "required": [ "steps" ], "additionalProperties": false }, "benchSettings": { "type": "object", "properties": { "balanceId": { "type": "string", "minLength": 1, "maxLength": 500 }, "minimumWeighableMassG": { "type": "number", "exclusiveMinimum": 0, "maximum": 2000 }, "vessel": { "type": "string", "minLength": 1, "maxLength": 500 }, "mixer": { "type": "string", "minLength": 1, "maxLength": 500 }, "temperatureC": { "type": "number", "minimum": 0, "maximum": 60 }, "mixingSeconds": { "type": "integer", "minimum": 1, "maximum": 3600 }, "mixingMethod": { "type": "string", "minLength": 1, "maxLength": 500 }, "temperatureToleranceC": { "type": "number", "minimum": 0, "maximum": 10 }, "massTolerancePercent": { "type": "number", "minimum": 0.1, "maximum": 10 }, "samplingMethod": { "type": "string", "minLength": 1, "maxLength": 500 }, "holdInstructions": { "type": "string", "minLength": 1, "maxLength": 500 }, "chillTemperatureC": { "default": null, "anyOf": [ { "type": "number", "minimum": 0, "maximum": 25 }, { "type": "null" } ] }, "chillSeconds": { "default": null, "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 86400 }, { "type": "null" } ] }, "chillMethod": { "default": "", "type": "string", "maxLength": 500 }, "carbonationEquipment": { "default": "", "type": "string", "maxLength": 500 }, "carbonationProcedure": { "default": "", "type": "string", "maxLength": 2000 } }, "required": [ "balanceId", "minimumWeighableMassG", "vessel", "mixer", "temperatureC", "mixingSeconds", "mixingMethod", "temperatureToleranceC", "massTolerancePercent", "samplingMethod", "holdInstructions" ], "additionalProperties": false } }, "required": [ "source", "name", "catalogVersion", "batchMassG", "ingredients" ], "additionalProperties": false } ] }, "deliverables": { "default": [ "photo", "taste" ], "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "photo", "taste", "ship" ] } }, "variationIds": { "default": [], "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "reduced_20", "reduced_40" ] } }, "destination": { "type": "object", "properties": { "country": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "region": { "type": "string", "minLength": 2, "maxLength": 100 }, "postalCode": { "type": "string", "minLength": 3, "maxLength": 20 } }, "required": [ "country", "region", "postalCode" ], "additionalProperties": false } }, "required": [ "recipe" ], "additionalProperties": false }, "quoteHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "shareWithTeam": { "type": "boolean", "const": true }, "contactEmail": { "type": "string", "maxLength": 254, "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": "Required for API-key requests. Authenticated browser sessions use the verified account email instead and may omit this field; a supplied value is ignored for new browser orders." }, "shippingAddress": { "type": "object", "properties": { "recipient": { "type": "string", "minLength": 1, "maxLength": 100 }, "line1": { "type": "string", "minLength": 3, "maxLength": 150 }, "line2": { "default": "", "type": "string", "maxLength": 150 }, "city": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "recipient", "line1", "city" ], "additionalProperties": false }, "notes": { "default": "", "type": "string", "maxLength": 2000 }, "originalBrief": { "type": "string", "minLength": 3, "maxLength": 3000 }, "relatedOrderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "checkout": { "type": "object", "properties": { "acceptQuote": { "type": "boolean", "const": true } }, "required": [ "acceptQuote" ], "additionalProperties": false, "description": "Optional normal checkout. Send {acceptQuote:true} only after showing the exact recipe, scope, complete quoted total and trial terms and obtaining customer consent. A complete supported quote and server paymentMode test or stripe_test are required. Omitting checkout saves a supported priced request awaiting_checkout without consent or payment; continue through /orders/{id}/checkout after explicit acceptance. No caller totals, terms overrides or payment fields are accepted." } }, "required": [ "selection", "quoteHash", "shareWithTeam", "contactEmail" ], "additionalProperties": false, "description": "Machine REST contract: contactEmail is required. For same-origin authenticated browser sessions, contactEmail may be omitted because the server uses the verified account email; a supplied value is ignored for new orders. Guest browser sessions cannot POST /orders and receive 401 AUTHENTICATION_REQUIRED. Browser login attaches the order and its lab report to the account." }, "SampleShippingQuote": { "type": "object", "properties": { "requested": { "type": "boolean" }, "status": { "enum": [ "not_requested", "review_required", "estimated" ] }, "totalCents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "policyVersion": { "type": "string" }, "basis": { "type": "string" }, "includes": { "type": "array", "items": { "type": "string" } }, "transitNote": { "type": "string" }, "plannedSampleCount": { "type": "integer" }, "reason": { "type": "string" }, "destination": { "type": "object", "properties": { "postalCode": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "country": { "const": "US" } }, "required": [ "postalCode", "city", "region", "country" ] } }, "required": [ "requested", "status", "totalCents" ], "description": "Shipped samples are for research only. Not for human or animal consumption. Optional planning estimate, not a carrier quote. estimated provides a $99-$209 planning allowance for one cool-packed overnight parcel, based on straight-line ZIP-centroid distance from origin 94133 (San Francisco, CA), using bundled GeoNames data. destination contains the resolved ZIP, city, state and country without coordinates. packageTotalCents plus shipping.totalCents is the full estimated order total. plannedSampleCount is one per recipe version, regardless of repeats, at most three. Insulation, gel packs, leak-resistant packaging, carrier allowance and a buffer are included. Only recognized ZIPs in the contiguous U.S. and D.C. with matching supplied states are estimated; unknown, mismatched or unsupported destinations retain review_required and a null shipping cost. The quote hash binds the origin, distance-tier policy, GeoNames dataset version and destination. Overnight transit starts after approved dispatch, not order submission; arrival time and temperature are not guaranteed. Legacy frozen receipts may have only requested, status and totalCents." }, "ServiceQuote": { "type": "object", "properties": { "kind": { "const": "service_quote" }, "currency": { "const": "USD" }, "binding": { "const": false }, "status": { "enum": [ "provisional", "quote_required" ] }, "totalCents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "packageTotalCents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "shipping": { "$ref": "#/components/schemas/SampleShippingQuote" }, "scopeHash": { "type": "string" }, "deliverables": { "type": "array", "items": { "enum": [ "photo", "taste", "ship" ] } }, "versions": { "type": "integer" }, "preparations": { "type": "integer" }, "batchMassG": { "type": "number" }, "sampleMassG": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Planned upper sample-mass cap in grams per recipe version when shipping is estimated, subject to actual yield and lab approval; never evidence of an existing or shipped sample. At most 100 g per version and no more than the planned batch quantity. The parcel covers at most three versions / 300 g total sample contents." }, "destination": { "anyOf": [ { "type": "object", "properties": { "country": { "type": "string" }, "region": { "type": "string" }, "postalCode": { "type": "string" } }, "required": [ "country", "region", "postalCode" ] }, { "type": "null" } ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "totalCents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "label", "totalCents" ] } }, "includes": { "type": "array", "items": { "type": "string" } }, "exclusions": { "type": "array", "items": { "type": "string" } }, "reasons": { "type": "array", "items": { "type": "string" } }, "reviewNotes": { "type": "array", "items": { "type": "string" } }, "notice": { "type": "string" } }, "required": [ "kind", "currency", "binding", "status", "totalCents", "scopeHash", "deliverables", "versions", "preparations", "batchMassG", "sampleMassG", "destination", "items", "includes", "exclusions", "reasons", "notice" ], "description": "Recipe-specific customer quote. A numeric total alone is planning, not order eligibility: require offer.review.eligible=true and current server-side physical qualification. Missing or expired exact-product/application qualification returns 422 PHYSICAL_QUALIFICATION_REQUIRED on submission. Prices depend on the exact ingredients, quantities and selected preparations. Extra flavors, premium ingredients, carbonation, chilling and longer mixing can increase the quote. Always display the server price for the exact selection. packageTotalCents is the trial subtotal; optional shipping is separate. A null total is not orderable. Explain the capability gap and select a supported alternative. Once submitted, a complete quote is fixed for its original scope; checkout proceeds directly into Ordered - Pending Lab. Scheduling and actual physical work are separate. Changed scope requires a new quote and explicit acceptance." }, "ServiceRecipe": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "hypothesis": { "type": "string" }, "methodNote": { "type": "string" }, "changes": { "type": "array", "items": { "type": "object", "properties": { "ingredientId": { "type": "string" }, "name": { "type": "string" }, "fromG": { "type": "number" }, "toG": { "type": "number" } }, "required": [ "ingredientId", "name", "fromG", "toG" ] } }, "name": { "type": "string" }, "batchMassG": { "type": "number" }, "replicates": { "type": "integer" }, "ingredients": { "type": "array", "items": { "type": "object", "properties": { "ingredientId": { "type": "string" }, "name": { "type": "string" }, "sourceMassG": { "type": "number" } }, "required": [ "ingredientId", "name", "sourceMassG" ] } }, "processSteps": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "label", "hypothesis", "methodNote", "changes", "name", "batchMassG", "replicates", "ingredients", "processSteps" ] }, "ServiceOffer": { "type": "object", "properties": { "review": { "type": "object", "properties": { "eligible": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "eligible", "reasons" ] }, "quote": { "$ref": "#/components/schemas/ServiceQuote" }, "trialProposal": { "type": "object", "properties": { "available": { "type": "boolean" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "axis": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceRecipe" } } }, "required": [ "available", "reason", "axis", "candidates" ] }, "selectedRecipes": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceRecipe" } } }, "required": [ "review", "quote", "trialProposal", "selectedRecipes" ] }, "TestPayment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "provider": { "enum": [ "simulated", "stripe" ] }, "mode": { "const": "test" }, "status": { "enum": [ "pending", "succeeded", "failed", "cancelled" ] }, "amountCents": { "type": "integer", "minimum": 1 }, "currency": { "const": "USD" }, "quoteHash": { "type": "string" }, "fundsCaptured": { "const": false }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "attempts": { "type": "integer", "minimum": 0, "maximum": 20 }, "lastAttemptId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "succeededAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "notice": { "type": "string" }, "checkoutSessionId": { "type": "string" }, "paymentIntentId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "checkoutExpiresAt": { "type": "string", "format": "date-time" }, "reviewRequired": { "type": "boolean" }, "reviewReason": { "type": "string" }, "offerId": { "type": "string", "format": "uuid" }, "offerHash": { "type": "string" } }, "required": [ "id", "provider", "mode", "status", "amountCents", "currency", "quoteHash", "fundsCaptured", "createdAt", "updatedAt", "attempts", "lastAttemptId", "succeededAt", "notice" ], "description": "Server-created sandbox payment record. provider simulated uses the internal test outcome endpoint; provider stripe uses hosted Stripe sandbox Checkout. Both retain mode test and fundsCaptured false: no real funds are collected. Amount and quote hash come from the saved accepted order, never caller totals. A return URL is not payment proof. Stripe success is recorded only by a verified signed webhook, reconciled against the current server-side session." }, "SimulateTestPayment": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "succeeded", "failed", "cancelled" ] } }, "required": [ "outcome" ], "additionalProperties": false }, "ServiceOrderStatus": { "type": "string", "enum": [ "awaiting_checkout", "ordered_pending_lab", "preparing", "reporting", "complete", "on_hold", "cancelled", "closed" ], "description": "Derived from payment and fulfillment. Display ordered_pending_lab as Ordered - Pending Lab. Awaiting checkout never implies payment. Completed published output takes precedence." }, "TestPaymentResult": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid" }, "revision": { "type": "integer" }, "orderStatus": { "$ref": "#/components/schemas/ServiceOrderStatus" }, "payment": { "$ref": "#/components/schemas/TestPayment" } }, "required": [ "orderId", "revision", "orderStatus", "payment" ] }, "SavedQuoteCheckout": { "type": "object", "properties": { "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "quoteHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "acceptQuote": { "type": "boolean", "const": true } }, "required": [ "revision", "quoteHash", "acceptQuote" ], "additionalProperties": false }, "LabStatus": { "type": "object", "properties": { "acceptingOrders": { "type": "boolean" }, "revision": { "type": "integer", "minimum": 1 }, "message": { "type": "string" }, "paymentMode": { "enum": [ "test", "stripe_test", "unconfigured" ] } }, "required": [ "acceptingOrders", "revision", "message", "paymentMode" ], "description": "Public intake and server payment mode. test is an internal simulator; stripe_test is hosted Stripe sandbox Checkout. Neither captures real money. unconfigured does not enable checkout. The same additive paymentMode field is returned by authorized browser GET/POST /admin/lab-status; that endpoint cannot change payment mode." }, "StripeCheckout": { "type": "object", "properties": { "paymentId": { "type": "string", "format": "uuid" } }, "required": [ "paymentId" ], "additionalProperties": false }, "StripeCheckoutResult": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid" }, "revision": { "type": "integer" }, "orderStatus": { "$ref": "#/components/schemas/ServiceOrderStatus" }, "payment": { "$ref": "#/components/schemas/TestPayment" }, "awaitingConfirmation": { "type": "boolean" }, "checkout": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "pattern": "^https://checkout\\.stripe\\.com/" }, "sessionId": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "url", "sessionId", "expiresAt" ] }, { "type": "null" } ] } }, "required": [ "orderId", "revision", "orderStatus", "payment", "awaitingConfirmation", "checkout" ] }, "RecordBatch": { "type": "object", "properties": { "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "recipeId": { "type": "string", "maxLength": 100 }, "batchId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "preparedAt": { "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))$" }, "maker": { "type": "string", "minLength": 1, "maxLength": 100 }, "ingredients": { "minItems": 1, "maxItems": 22, "type": "array", "items": { "type": "object", "properties": { "ingredientId": { "type": "string", "maxLength": 100 }, "actualMassG": { "type": "number", "minimum": 0, "maximum": 5000 }, "lot": { "type": "string", "minLength": 1, "maxLength": 150 } }, "required": [ "ingredientId", "actualMassG", "lot" ], "additionalProperties": false } }, "process": { "type": "string", "maxLength": 3000 }, "measurements": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "mass", "ph", "brix", "conductivity", "turbidity", "sensory" ] }, "value": { "type": [ "number", "null" ] }, "unit": { "type": "string", "maxLength": 30 }, "reason": { "type": "string", "maxLength": 3000 }, "method": { "type": "string", "maxLength": 3000 }, "instrument": { "type": "string", "maxLength": 200 }, "calibration": { "type": "string", "maxLength": 3000 }, "measuredAt": { "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))$" }, { "type": "null" } ] } }, "required": [ "metric", "value", "unit", "reason", "method", "instrument", "calibration", "measuredAt" ], "additionalProperties": false } }, "appearance": { "type": "string", "maxLength": 3000 }, "tastingNotes": { "type": "string", "maxLength": 3000 }, "tastingOmittedReason": { "type": "string", "maxLength": 3000 }, "internalTastingReview": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "not_tasted", "tasted" ] }, "approvedForTasting": { "type": "boolean" }, "assessmentReference": { "type": "string", "maxLength": 2000 } }, "required": [ "status", "approvedForTasting", "assessmentReference" ], "additionalProperties": false }, "photos": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "caption": { "type": "string", "minLength": 1, "maxLength": 300 } }, "required": [ "id", "caption" ], "additionalProperties": false } }, "photosOmittedReason": { "type": "string", "maxLength": 3000 }, "deviations": { "type": "string", "maxLength": 3000 }, "nextStep": { "type": "string", "maxLength": 3000 }, "supersedesId": { "default": null, "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "correctionReason": { "default": "", "type": "string", "maxLength": 3000 } }, "required": [ "revision", "recipeId", "batchId", "preparedAt", "maker", "ingredients", "process", "measurements", "appearance", "tastingNotes", "tastingOmittedReason", "photos", "photosOmittedReason", "deviations", "nextStep" ], "additionalProperties": false }, "SharedBatchRecord": { "type": "object", "properties": { "recipeId": { "type": "string", "maxLength": 100 }, "batchId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "preparedAt": { "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))$" }, "maker": { "type": "string", "minLength": 1, "maxLength": 100 }, "ingredients": { "minItems": 1, "maxItems": 22, "type": "array", "items": { "type": "object", "properties": { "ingredientId": { "type": "string", "maxLength": 100 }, "actualMassG": { "type": "number", "minimum": 0, "maximum": 5000 }, "lot": { "type": "string", "minLength": 1, "maxLength": 150 } }, "required": [ "ingredientId", "actualMassG", "lot" ], "additionalProperties": false } }, "process": { "type": "string", "maxLength": 3000 }, "measurements": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "mass", "ph", "brix", "conductivity", "turbidity", "sensory" ] }, "value": { "type": [ "number", "null" ] }, "unit": { "type": "string", "maxLength": 30 }, "reason": { "type": "string", "maxLength": 3000 }, "method": { "type": "string", "maxLength": 3000 }, "instrument": { "type": "string", "maxLength": 200 }, "calibration": { "type": "string", "maxLength": 3000 }, "measuredAt": { "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))$" }, { "type": "null" } ] } }, "required": [ "metric", "value", "unit", "reason", "method", "instrument", "calibration", "measuredAt" ], "additionalProperties": false } }, "appearance": { "type": "string", "maxLength": 3000 }, "tastingNotes": { "type": "string", "maxLength": 3000 }, "tastingOmittedReason": { "type": "string", "maxLength": 3000 }, "photos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "caption": { "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "caption", "url" ] } }, "photosOmittedReason": { "type": "string", "maxLength": 3000 }, "deviations": { "type": "string", "maxLength": 3000 }, "nextStep": { "type": "string", "maxLength": 3000 }, "supersedesId": { "default": null, "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "correctionReason": { "default": "", "type": "string", "maxLength": 3000 }, "id": { "type": "string", "format": "uuid" }, "recordedAt": { "type": "string", "format": "date-time" } }, "required": [ "recipeId", "batchId", "preparedAt", "maker", "ingredients", "process", "measurements", "appearance", "tastingNotes", "tastingOmittedReason", "photos", "photosOmittedReason", "deviations", "nextStep", "supersedesId", "correctionReason", "id", "recordedAt" ] }, "BatchReport": { "type": "object", "properties": { "assessment": { "$ref": "#/components/schemas/ServiceAssessmentView" }, "status": { "enum": [ "not_started", "partial", "assessment_pending", "reported", "reported_with_omissions" ] }, "expectedBatches": { "type": "integer" }, "recordedBatches": { "type": "integer" }, "omissions": { "type": "integer" }, "notice": { "type": "string" }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/SharedBatchRecord" } }, "batches": { "type": "array", "items": { "type": "object", "properties": { "recipeId": { "type": "string" }, "label": { "type": "string" }, "batchId": { "type": "string", "format": "uuid" }, "replicate": { "type": "integer" }, "targetMassG": { "type": "number" }, "targetIngredients": { "type": "array", "items": { "type": "object", "properties": { "ingredientId": { "type": "string" }, "name": { "type": "string" }, "targetMassG": { "type": "number" } }, "required": [ "ingredientId", "name", "targetMassG" ] } }, "requestedTests": { "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string" }, "min": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "metric", "min", "max" ] } }, "record": { "anyOf": [ { "$ref": "#/components/schemas/SharedBatchRecord" }, { "type": "null" } ] }, "ingredientDifferences": { "type": "array", "items": { "type": "object", "properties": { "ingredientId": { "type": "string" }, "name": { "type": "string" }, "targetMassG": { "type": "number" }, "actualMassG": { "type": "number" }, "lot": { "type": "string" }, "deviationG": { "type": "number" } }, "required": [ "ingredientId", "name", "targetMassG", "actualMassG", "lot", "deviationG" ] } }, "checks": { "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string" }, "min": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "max": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "enum": [ "pending", "not_measured", "recorded", "outside_target", "within_target" ] } }, "required": [ "metric", "min", "max", "status" ] } } }, "required": [ "recipeId", "label", "batchId", "replicate", "targetMassG", "targetIngredients", "requestedTests", "record", "ingredientDifferences", "checks" ] } } }, "required": [ "assessment", "status", "expectedBatches", "recordedBatches", "omissions", "notice", "history", "batches" ], "description": "Owner-scoped shared evidence for every expected preparation. not_started and partial describe missing batch records. assessment_pending means all batch records exist but accepted criteria still need an assessment or reassessment after correction. reported and reported_with_omissions describe publication, not a guarantee that targets were achieved. Read assessment.current.criteria for each verdict; omitted measurements remain null with reasons. Batch and assessment history are append-only." }, "RecordServiceAssessment": { "type": "object", "properties": { "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "offerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "offerHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "criteria": { "minItems": 2, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "criterionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "recipeId": { "type": "string", "minLength": 1, "maxLength": 100 }, "verdict": { "type": "string", "enum": [ "achieved", "partly_achieved", "not_achieved", "not_assessed" ] }, "explanation": { "type": "string", "minLength": 1, "maxLength": 3000 }, "evidence": { "maxItems": 18, "type": "array", "items": { "type": "object", "properties": { "recordId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "field": { "type": "string", "enum": [ "appearance", "tastingNotes", "measurement" ] }, "metric": { "type": "string", "enum": [ "mass", "ph", "brix", "conductivity", "turbidity", "sensory" ] } }, "required": [ "recordId", "field" ], "additionalProperties": false } } }, "required": [ "criterionId", "recipeId", "verdict", "explanation", "evidence" ], "additionalProperties": false } }, "comparison": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "single_version", "preferred", "no_clear_winner", "not_assessed" ] }, "preferredRecipeId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 3000 } }, "required": [ "status", "preferredRecipeId", "reason" ], "additionalProperties": false }, "nextStep": { "type": "string", "minLength": 1, "maxLength": 3000 }, "supersedesId": { "default": null, "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "correctionReason": { "default": "", "type": "string", "maxLength": 3000 } }, "required": [ "revision", "offerId", "offerHash", "criteria", "comparison", "nextStep" ], "additionalProperties": false }, "SharedServiceAssessment": { "type": "object", "properties": { "recordKind": { "const": "service_assessment" }, "id": { "type": "string", "format": "uuid" }, "offerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "offerHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "recordedAt": { "type": "string", "format": "date-time" }, "criteria": { "minItems": 2, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "criterionId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "recipeId": { "type": "string", "minLength": 1, "maxLength": 100 }, "verdict": { "type": "string", "enum": [ "achieved", "partly_achieved", "not_achieved", "not_assessed" ] }, "explanation": { "type": "string", "minLength": 1, "maxLength": 3000 }, "evidence": { "maxItems": 18, "type": "array", "items": { "type": "object", "properties": { "recordId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "field": { "type": "string", "enum": [ "appearance", "tastingNotes", "measurement" ] }, "metric": { "type": "string", "enum": [ "mass", "ph", "brix", "conductivity", "turbidity", "sensory" ] } }, "required": [ "recordId", "field" ], "additionalProperties": false } } }, "required": [ "criterionId", "recipeId", "verdict", "explanation", "evidence" ], "additionalProperties": false } }, "comparison": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "single_version", "preferred", "no_clear_winner", "not_assessed" ] }, "preferredRecipeId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 3000 } }, "required": [ "status", "preferredRecipeId", "reason" ], "additionalProperties": false }, "nextStep": { "type": "string", "minLength": 1, "maxLength": 3000 }, "recordIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "supersedesId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "correctionReason": { "type": "string" } }, "required": [ "recordKind", "id", "offerId", "offerHash", "recordedAt", "criteria", "comparison", "nextStep", "recordIds", "supersedesId", "correctionReason" ], "description": "Immutable operator assessment of every accepted criterion for every ordered recipe version. Evidence points to current shared batch records. actor and private procurement/economics data are omitted. not_assessed has an explanation and no evidence claim; a missing observation is never a pass or a zero." }, "ServiceAssessmentView": { "type": "object", "properties": { "status": { "enum": [ "not_agreed", "pending", "published", "stale" ] }, "brief": { "type": "object", "properties": { "status": { "enum": [ "recorded", "not_recorded" ] }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "status", "text" ] }, "alternative": { "anyOf": [ { "type": "object", "properties": { "description": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "description", "reason" ] }, { "type": "null" } ] }, "agreedCriteria": { "type": "array", "items": { "$ref": "#/components/schemas/OfferCriterion" } }, "current": { "anyOf": [ { "$ref": "#/components/schemas/SharedServiceAssessment" }, { "type": "null" } ] }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/SharedServiceAssessment" } } }, "required": [ "status", "brief", "alternative", "agreedCriteria", "current", "history" ], "description": "not_agreed means no accepted criterion contract is recorded, including legacy work; pending means no assessment yet; published means the latest assessment matches the accepted offer and every current batch record; stale means an evidence correction invalidated it. current is null unless published. history preserves prior assessments without presenting them as current conclusions. The original brief is kept verbatim; operator prose is filtered for private sourcing details." }, "ServiceAssessmentPreview": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid" }, "revision": { "type": "integer" }, "preview": { "const": true }, "results": { "$ref": "#/components/schemas/BatchReport" } }, "required": [ "orderId", "revision", "preview", "results" ] }, "ServiceAssessmentResult": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid" }, "revision": { "type": "integer" }, "results": { "$ref": "#/components/schemas/BatchReport" }, "assessmentId": { "type": "string", "format": "uuid" } }, "required": [ "orderId", "revision", "results", "assessmentId" ] }, "RefinementReference": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "generation", "idea", "order" ] }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "recipeId": { "type": "string", "minLength": 1, "maxLength": 100 }, "variantId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "source", "id", "revision" ], "additionalProperties": false }, "RefinementBrief": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "family": { "type": "string" }, "objective": { "default": "", "type": "string", "maxLength": 2000 }, "batchMassG": { "type": "number", "minimum": 100, "maximum": 2000 }, "sugarGPer100g": { "type": "number", "minimum": 0, "maximum": 12 }, "acidGPerKg": { "type": "number", "minimum": 0, "maximum": 5 }, "sweetener": { "type": "string", "enum": [ "sweet.sucrose", "sweet.allulose", "sweet.erythritol", "sweet.dextrose" ] }, "primaryFlavor": { "type": "string" }, "accentFlavor": { "default": "none", "type": "string" }, "carbonated": { "type": "boolean" }, "variantCount": { "default": 3, "anyOf": [ { "type": "number", "const": 1 }, { "type": "number", "const": 3 }, { "type": "number", "const": 6 } ] }, "studio": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "beverage", "flavor" ] }, "includeJuices": { "type": "boolean" }, "notes": { "maxItems": 30, "type": "array", "items": { "type": "string", "maxLength": 1000 } }, "unmatched": { "maxItems": 300, "type": "array", "items": { "type": "string", "maxLength": 100 } }, "ai": { "type": "object", "properties": { "generationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "extendedIngredientIds": { "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 100 } }, "requestScope": { "type": "string", "enum": [ "beverage", "water_flavor", "outside_scope" ] }, "model": { "type": "string", "maxLength": 100 }, "ingredientLibraryVersion": { "type": "string", "maxLength": 100 }, "generatedAt": { "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))$" }, "explanation": { "type": "string", "maxLength": 1600 }, "constraints": { "type": "object", "properties": { "noAddedSweetener": { "type": "boolean" }, "excludedIngredientIds": { "maxItems": 166, "type": "array", "items": { "type": "string", "maxLength": 100 } }, "requiredAllergenExclusions": { "maxItems": 9, "type": "array", "items": { "type": "string", "enum": [ "milk", "egg", "fish", "crustacean_shellfish", "tree_nut", "peanut", "wheat", "soy", "sesame" ] } } }, "required": [ "noAddedSweetener", "excludedIngredientIds" ], "additionalProperties": false }, "missingIngredients": { "maxItems": 15, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "reason": { "type": "string", "maxLength": 500 }, "alternatives": { "maxItems": 5, "type": "array", "items": { "type": "string", "maxLength": 100 } } }, "required": [ "name", "reason", "alternatives" ], "additionalProperties": false } }, "questions": { "maxItems": 8, "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string", "maxLength": 500 }, "blocking": { "type": "boolean" } }, "required": [ "question", "blocking" ], "additionalProperties": false } }, "rationales": { "maxItems": 59, "type": "array", "items": { "type": "object", "properties": { "ingredientId": { "type": "string", "maxLength": 100 }, "reason": { "type": "string", "maxLength": 500 } }, "required": [ "ingredientId", "reason" ], "additionalProperties": false } }, "conversation": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string", "maxLength": 1600 } }, "required": [ "role", "content" ], "additionalProperties": false } }, "manuallyEdited": { "type": "boolean" }, "concept": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "pitch": { "type": "string", "minLength": 1, "maxLength": 600 }, "approach": { "type": "string", "minLength": 1, "maxLength": 600 }, "identityRequirements": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "string", "maxLength": 600 } }, "materials": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "catalogId": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "role": { "type": "string", "maxLength": 300 } }, "required": [ "name", "catalogId", "role" ], "additionalProperties": false } }, "processSteps": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "string", "maxLength": 600 } }, "testPlan": { "type": "object", "properties": { "comparison": { "type": "string", "maxLength": 600 }, "checks": { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "measure": { "type": "string", "maxLength": 300 }, "target": { "type": "string", "maxLength": 300 } }, "required": [ "measure", "target" ], "additionalProperties": false } }, "decision": { "type": "string", "maxLength": 600 } }, "required": [ "comparison", "checks", "decision" ], "additionalProperties": false }, "tradeoff": { "type": "string", "maxLength": 600 }, "nextStep": { "type": "string", "maxLength": 600 }, "requiresDevelopment": { "type": "boolean" } }, "required": [ "title", "pitch", "approach", "identityRequirements", "materials", "processSteps", "testPlan", "tradeoff", "nextStep", "requiresDevelopment" ], "additionalProperties": false }, "fulfillment": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "supported", "alternative", "development_required", "unsupported" ] }, "approach": { "type": "string", "minLength": 1, "maxLength": 360 }, "reason": { "type": "string", "maxLength": 280 }, "compromise": { "type": "string", "maxLength": 280 }, "processes": { "maxItems": 6, "type": "array", "items": { "type": "string", "enum": [ "weigh", "dissolve", "blend", "chill", "carbonate", "clarify", "extract", "emulsify", "custom_process" ] } } }, "required": [ "status", "approach", "reason", "compromise", "processes" ], "additionalProperties": false }, "iterations": { "minItems": 2, "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "stage": { "type": "string", "enum": [ "explore", "improve", "finalize" ] }, "model": { "type": "string", "maxLength": 100 }, "summary": { "type": "string", "maxLength": 600 }, "durationMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "attempts": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "inputTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "outputTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "reasoningTokens": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "stage", "model", "summary" ], "additionalProperties": false } } }, "required": [ "generationId", "model", "generatedAt", "explanation", "constraints", "missingIngredients", "questions", "rationales", "conversation", "manuallyEdited" ], "additionalProperties": false } }, "required": [ "kind", "includeJuices", "notes", "unmatched" ], "additionalProperties": false } }, "required": [ "name", "family", "batchMassG", "sugarGPer100g", "acidGPerKg", "sweetener", "primaryFlavor", "carbonated" ], "additionalProperties": false }, "RefinementRecipe": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "change": { "type": "string", "maxLength": 300 }, "isControl": { "type": "boolean" }, "lines": { "minItems": 1, "maxItems": 59, "type": "array", "items": { "type": "object", "properties": { "ingredientId": { "type": "string" }, "sourceMassG": { "type": "number", "minimum": 0, "maximum": 2000 }, "stockFraction": { "default": 1, "type": "number", "exclusiveMinimum": 0, "maximum": 1 } }, "required": [ "ingredientId", "sourceMassG" ], "additionalProperties": false } } }, "required": [ "id", "name", "change", "isControl", "lines" ], "additionalProperties": false }, "RefinementContext": { "type": "object", "properties": { "reference": { "$ref": "#/components/schemas/RefinementReference" }, "brief": { "$ref": "#/components/schemas/RefinementBrief" }, "recipe": { "$ref": "#/components/schemas/RefinementRecipe" }, "priorProcess": { "type": "array", "items": { "type": "string" } }, "evidence": { "anyOf": [ { "type": "object", "description": "For order sources, sanitized current recorded observations, agreed criteria, original brief/alternative, assessment status and current assessment only when published. A stale assessment is not reused as a current verdict. Otherwise null." }, { "type": "null" } ] }, "previousUrl": { "type": "string" }, "relatedOrderId": { "type": "string", "format": "uuid" }, "ingredients": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "sourceMassG": { "type": "number" } }, "required": [ "name", "sourceMassG" ] } } }, "required": [ "reference", "brief", "recipe", "priorProcess", "evidence", "previousUrl", "ingredients" ] }, "ReleaseServiceWork": { "type": "object", "properties": { "action": { "type": "string", "const": "review" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "recipes": { "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "recipeId": { "type": "string", "minLength": 1, "maxLength": 100 }, "settings": { "type": "object", "properties": { "balanceId": { "type": "string", "minLength": 1, "maxLength": 500 }, "minimumWeighableMassG": { "type": "number", "exclusiveMinimum": 0, "maximum": 2000 }, "vessel": { "type": "string", "minLength": 1, "maxLength": 500 }, "mixer": { "type": "string", "minLength": 1, "maxLength": 500 }, "temperatureC": { "type": "number", "minimum": 0, "maximum": 60 }, "mixingSeconds": { "type": "integer", "minimum": 1, "maximum": 3600 }, "mixingMethod": { "type": "string", "minLength": 1, "maxLength": 500 }, "temperatureToleranceC": { "type": "number", "minimum": 0, "maximum": 10 }, "massTolerancePercent": { "type": "number", "minimum": 0.1, "maximum": 10 }, "samplingMethod": { "type": "string", "minLength": 1, "maxLength": 500 }, "holdInstructions": { "type": "string", "minLength": 1, "maxLength": 500 }, "chillTemperatureC": { "default": null, "anyOf": [ { "type": "number", "minimum": 0, "maximum": 25 }, { "type": "null" } ] }, "chillSeconds": { "default": null, "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 86400 }, { "type": "null" } ] }, "chillMethod": { "default": "", "type": "string", "maxLength": 500 }, "carbonationEquipment": { "default": "", "type": "string", "maxLength": 500 }, "carbonationProcedure": { "default": "", "type": "string", "maxLength": 2000 } }, "required": [ "balanceId", "minimumWeighableMassG", "vessel", "mixer", "temperatureC", "mixingSeconds", "mixingMethod", "temperatureToleranceC", "massTolerancePercent", "samplingMethod", "holdInstructions" ], "additionalProperties": false }, "lots": { "type": "object", "propertyNames": { "type": "string", "maxLength": 100 }, "additionalProperties": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "carbonationLotId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "recipeId", "settings", "lots" ], "additionalProperties": false } }, "note": { "type": "string", "minLength": 5, "maxLength": 2000 }, "confirm": { "type": "boolean", "const": true }, "testOverrideReason": { "type": "string", "minLength": 10, "maxLength": 1000 } }, "required": [ "action", "revision", "recipes", "note", "confirm" ], "additionalProperties": false }, "CustomerDeliveryCommand": { "oneOf": [ { "type": "object", "properties": { "action": { "type": "string", "const": "confirm_address" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "address": { "type": "object", "properties": { "recipient": { "type": "string", "minLength": 1, "maxLength": 100 }, "line1": { "type": "string", "minLength": 1, "maxLength": 150 }, "line2": { "default": "", "type": "string", "maxLength": 150 }, "city": { "type": "string", "minLength": 1, "maxLength": 100 }, "region": { "type": "string", "minLength": 1, "maxLength": 100 }, "postalCode": { "type": "string", "minLength": 1, "maxLength": 20 }, "country": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "required": [ "recipient", "line1", "city", "region", "postalCode", "country" ], "additionalProperties": false }, "confirm": { "type": "boolean", "const": true } }, "required": [ "action", "revision", "address", "confirm" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "report_issue" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "description": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "action", "revision", "description" ], "additionalProperties": false } ] }, "OperatorDeliveryCommand": { "oneOf": [ { "type": "object", "properties": { "action": { "type": "string", "const": "schedule_report" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "reportDueOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "message": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "action", "revision", "reportDueOn", "message" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "approve_package" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "dispatchOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "items": { "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "recipeId": { "type": "string", "minLength": 1, "maxLength": 100 }, "batchId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "recordId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "label": { "type": "string", "minLength": 1, "maxLength": 150 }, "massG": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 }, "allergens": { "type": "string", "minLength": 1, "maxLength": 1000 }, "storage": { "type": "string", "minLength": 1, "maxLength": 1000 }, "useInstructions": { "type": "string", "minLength": 1, "maxLength": 1000 }, "holdingRecordReference": { "type": "string", "minLength": 1, "maxLength": 1000 }, "storageMinimumC": { "type": "number", "minimum": -100, "maximum": 100 }, "storageMaximumC": { "type": "number", "minimum": -100, "maximum": 100 }, "researchLabel": { "type": "string", "const": "RESEARCH ONLY — NOT FOR HUMAN OR ANIMAL CONSUMPTION" } }, "required": [ "recipeId", "batchId", "recordId", "label", "massG", "allergens", "storage", "useInstructions", "holdingRecordReference", "storageMinimumC", "storageMaximumC", "researchLabel" ], "additionalProperties": false } }, "packaging": { "type": "string", "minLength": 1, "maxLength": 1000 }, "transportQualification": { "type": "object", "properties": { "reference": { "type": "string", "minLength": 1, "maxLength": 2000 }, "validatedAt": { "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))$" }, "validUntil": { "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))$" }, "minimumC": { "type": "number", "minimum": -100, "maximum": 100 }, "maximumC": { "type": "number", "minimum": -100, "maximum": 100 }, "maxHoldHours": { "type": "number", "exclusiveMinimum": 0, "maximum": 8760 }, "maxTransitHours": { "type": "number", "exclusiveMinimum": 0, "maximum": 168 }, "expectedTransitHours": { "type": "number", "exclusiveMinimum": 0, "maximum": 48 }, "packagingConfiguration": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "reference", "validatedAt", "validUntil", "minimumC", "maximumC", "maxHoldHours", "maxTransitHours", "expectedTransitHours", "packagingConfiguration" ], "additionalProperties": false }, "reviewed": { "type": "boolean", "const": true } }, "required": [ "action", "revision", "dispatchOn", "items", "packaging", "transportQualification", "reviewed" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "dispatch" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "packageId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "carrier": { "type": "string", "minLength": 1, "maxLength": 100 }, "trackingNumber": { "type": "string", "minLength": 1, "maxLength": 150 }, "trackingUrl": { "type": "string", "maxLength": 1000, "format": "uri" }, "packingEvidence": { "type": "object", "properties": { "packedAt": { "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))$" }, "measuredAt": { "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))$" }, "sampleTemperatureC": { "type": "number", "minimum": -100, "maximum": 100 }, "labelsApplied": { "type": "boolean", "const": true }, "packagingMatchesQualification": { "type": "boolean", "const": true }, "conditionConfirmed": { "type": "boolean", "const": true }, "recordReference": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "packedAt", "measuredAt", "sampleTemperatureC", "labelsApplied", "packagingMatchesQualification", "conditionConfirmed", "recordReference" ], "additionalProperties": false }, "confirmHandedToCarrier": { "type": "boolean", "const": true } }, "required": [ "action", "revision", "packageId", "carrier", "trackingNumber", "trackingUrl", "packingEvidence", "confirmHandedToCarrier" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "delivered" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "shipmentId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "confirmation": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "action", "revision", "shipmentId", "confirmation" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "resolve_issue" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "issueId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "resolution": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "action", "revision", "issueId", "resolution" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "record_notification" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "taskId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "channel": { "type": "string", "enum": [ "email", "phone", "in_person" ] }, "note": { "type": "string", "minLength": 1, "maxLength": 1000 }, "confirmSent": { "type": "boolean", "const": true } }, "required": [ "action", "revision", "taskId", "channel", "note", "confirmSent" ], "additionalProperties": false } ] }, "IssueFinalOffer": { "type": "object", "properties": { "action": { "type": "string", "const": "issue" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "selection": { "type": "object", "properties": { "recipe": { "oneOf": [ { "type": "object", "properties": { "replicates": { "default": 1, "type": "integer", "minimum": 1, "maximum": 3 }, "tests": { "default": [ { "metric": "mass", "min": null, "max": null } ], "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "ph", "brix", "mass", "conductivity", "turbidity", "sensory" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] } }, "required": [ "metric", "min", "max" ], "additionalProperties": false } }, "source": { "type": "string", "const": "idea" }, "ideaId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "ideaRevision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "acceptAlternative": { "default": false, "type": "boolean" }, "variantId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "source", "ideaId", "ideaRevision" ], "additionalProperties": false }, { "type": "object", "properties": { "replicates": { "default": 1, "type": "integer", "minimum": 1, "maximum": 3 }, "tests": { "default": [ { "metric": "mass", "min": null, "max": null } ], "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "ph", "brix", "mass", "conductivity", "turbidity", "sensory" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] } }, "required": [ "metric", "min", "max" ], "additionalProperties": false } }, "source": { "type": "string", "const": "generation" }, "generationId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "acceptAlternative": { "default": false, "type": "boolean" }, "variantId": { "type": "string", "minLength": 1, "maxLength": 64 } }, "required": [ "source", "generationId" ], "additionalProperties": false }, { "type": "object", "properties": { "replicates": { "default": 1, "type": "integer", "minimum": 1, "maximum": 3 }, "tests": { "default": [ { "metric": "mass", "min": null, "max": null } ], "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "ph", "brix", "mass", "conductivity", "turbidity", "sensory" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] } }, "required": [ "metric", "min", "max" ], "additionalProperties": false } }, "source": { "type": "string", "const": "ingredients" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "catalogVersion": { "type": "string", "minLength": 1, "maxLength": 100 }, "batchMassG": { "type": "number", "minimum": 100, "maximum": 2000 }, "ingredients": { "minItems": 1, "maxItems": 21, "type": "array", "items": { "type": "object", "properties": { "ingredientId": { "type": "string", "minLength": 1, "maxLength": 100 }, "sourceMassG": { "type": "number", "exclusiveMinimum": 0, "maximum": 2000 } }, "required": [ "ingredientId", "sourceMassG" ], "additionalProperties": false } }, "carbonated": { "default": false, "type": "boolean" }, "allergenRequirements": { "maxItems": 9, "type": "array", "items": { "type": "string", "enum": [ "milk", "egg", "fish", "crustacean_shellfish", "tree_nut", "peanut", "wheat", "soy", "sesame" ] } }, "application": { "type": "string", "enum": [ "beverage", "water_flavor" ] }, "preparation": { "type": "object", "properties": { "steps": { "minItems": 1, "maxItems": 30, "type": "array", "items": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 1500 }, { "oneOf": [ { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 1500 }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "const": "instruction" } }, "required": [ "instruction", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 1500 }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "const": "add" }, "ingredientId": { "type": "string", "minLength": 1, "maxLength": 100 }, "massG": { "type": "number", "exclusiveMinimum": 0, "maximum": 2000 } }, "required": [ "instruction", "type", "ingredientId" ], "additionalProperties": false }, { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 1500 }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "const": "mix" }, "temperatureC": { "type": "number", "minimum": 0, "maximum": 60 }, "durationSeconds": { "type": "integer", "minimum": 1, "maximum": 86400 } }, "required": [ "instruction", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 1500 }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "const": "chill" }, "temperatureC": { "type": "number", "minimum": 0, "maximum": 25 }, "durationSeconds": { "type": "integer", "minimum": 1, "maximum": 86400 } }, "required": [ "instruction", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "instruction": { "type": "string", "minLength": 1, "maxLength": 1500 }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "const": "carbonate" } }, "required": [ "instruction", "type" ], "additionalProperties": false } ] } ] } }, "notes": { "default": "", "type": "string", "maxLength": 2000 } }, "required": [ "steps" ], "additionalProperties": false }, "benchSettings": { "type": "object", "properties": { "balanceId": { "type": "string", "minLength": 1, "maxLength": 500 }, "minimumWeighableMassG": { "type": "number", "exclusiveMinimum": 0, "maximum": 2000 }, "vessel": { "type": "string", "minLength": 1, "maxLength": 500 }, "mixer": { "type": "string", "minLength": 1, "maxLength": 500 }, "temperatureC": { "type": "number", "minimum": 0, "maximum": 60 }, "mixingSeconds": { "type": "integer", "minimum": 1, "maximum": 3600 }, "mixingMethod": { "type": "string", "minLength": 1, "maxLength": 500 }, "temperatureToleranceC": { "type": "number", "minimum": 0, "maximum": 10 }, "massTolerancePercent": { "type": "number", "minimum": 0.1, "maximum": 10 }, "samplingMethod": { "type": "string", "minLength": 1, "maxLength": 500 }, "holdInstructions": { "type": "string", "minLength": 1, "maxLength": 500 }, "chillTemperatureC": { "default": null, "anyOf": [ { "type": "number", "minimum": 0, "maximum": 25 }, { "type": "null" } ] }, "chillSeconds": { "default": null, "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 86400 }, { "type": "null" } ] }, "chillMethod": { "default": "", "type": "string", "maxLength": 500 }, "carbonationEquipment": { "default": "", "type": "string", "maxLength": 500 }, "carbonationProcedure": { "default": "", "type": "string", "maxLength": 2000 } }, "required": [ "balanceId", "minimumWeighableMassG", "vessel", "mixer", "temperatureC", "mixingSeconds", "mixingMethod", "temperatureToleranceC", "massTolerancePercent", "samplingMethod", "holdInstructions" ], "additionalProperties": false } }, "required": [ "source", "name", "catalogVersion", "batchMassG", "ingredients" ], "additionalProperties": false } ] }, "deliverables": { "default": [ "photo", "taste" ], "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "photo", "taste", "ship" ] } }, "variationIds": { "default": [], "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "reduced_20", "reduced_40" ] } }, "destination": { "type": "object", "properties": { "country": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "region": { "type": "string", "minLength": 2, "maxLength": 100 }, "postalCode": { "type": "string", "minLength": 3, "maxLength": 20 } }, "required": [ "country", "region", "postalCode" ], "additionalProperties": false } }, "required": [ "recipe" ], "additionalProperties": false }, "settings": { "default": [], "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "recipeId": { "type": "string", "minLength": 1, "maxLength": 100 }, "settings": { "type": "object", "properties": { "balanceId": { "type": "string", "minLength": 1, "maxLength": 500 }, "minimumWeighableMassG": { "type": "number", "exclusiveMinimum": 0, "maximum": 2000 }, "vessel": { "type": "string", "minLength": 1, "maxLength": 500 }, "mixer": { "type": "string", "minLength": 1, "maxLength": 500 }, "temperatureC": { "type": "number", "minimum": 0, "maximum": 60 }, "mixingSeconds": { "type": "integer", "minimum": 1, "maximum": 3600 }, "mixingMethod": { "type": "string", "minLength": 1, "maxLength": 500 }, "temperatureToleranceC": { "type": "number", "minimum": 0, "maximum": 10 }, "massTolerancePercent": { "type": "number", "minimum": 0.1, "maximum": 10 }, "samplingMethod": { "type": "string", "minLength": 1, "maxLength": 500 }, "holdInstructions": { "type": "string", "minLength": 1, "maxLength": 500 }, "chillTemperatureC": { "default": null, "anyOf": [ { "type": "number", "minimum": 0, "maximum": 25 }, { "type": "null" } ] }, "chillSeconds": { "default": null, "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 86400 }, { "type": "null" } ] }, "chillMethod": { "default": "", "type": "string", "maxLength": 500 }, "carbonationEquipment": { "default": "", "type": "string", "maxLength": 500 }, "carbonationProcedure": { "default": "", "type": "string", "maxLength": 2000 } }, "required": [ "balanceId", "minimumWeighableMassG", "vessel", "mixer", "temperatureC", "mixingSeconds", "mixingMethod", "temperatureToleranceC", "massTolerancePercent", "samplingMethod", "holdInstructions" ], "additionalProperties": false } }, "required": [ "recipeId", "settings" ], "additionalProperties": false } }, "criteria": { "minItems": 2, "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "target": { "type": "string", "minLength": 1, "maxLength": 600 }, "method": { "type": "string", "enum": [ "maker_observation", "visual_observation", "instrument_reading" ] }, "metric": { "type": "string", "enum": [ "ph", "brix", "mass", "conductivity", "turbidity", "sensory" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] } }, "required": [ "label", "target", "method" ], "additionalProperties": false } }, "scheduledBenchOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "reportDueOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "expiresAt": { "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))$" }, "trialCents": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "shippingCents": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "taxCents": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "taxTreatment": { "type": "string", "minLength": 1, "maxLength": 500 }, "shippingReview": { "type": "object", "properties": { "sampleMassGPerVersion": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 }, "note": { "type": "string", "minLength": 1, "maxLength": 1500 } }, "required": [ "sampleMassGPerVersion", "note" ], "additionalProperties": false }, "measurementMethods": { "default": [], "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "metric": { "type": "string", "enum": [ "ph", "brix", "mass", "conductivity", "turbidity", "sensory" ] }, "instrument": { "type": "string", "minLength": 1, "maxLength": 300 }, "method": { "type": "string", "minLength": 1, "maxLength": 1000 }, "verification": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "metric", "instrument", "method", "verification" ], "additionalProperties": false } }, "changes": { "default": "", "type": "string", "maxLength": 2000 }, "alternative": { "default": null, "anyOf": [ { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 1000 }, "reason": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "description", "reason" ], "additionalProperties": false }, { "type": "null" } ] }, "terms": { "type": "object", "properties": { "cancellation": { "type": "string", "minLength": 1, "maxLength": 1500 }, "rework": { "type": "string", "minLength": 1, "maxLength": 1500 }, "shipmentRemedy": { "type": "string", "minLength": 1, "maxLength": 1500 }, "contactEmail": { "type": "string", "maxLength": 254, "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,}$" } }, "required": [ "cancellation", "rework", "shipmentRemedy", "contactEmail" ], "additionalProperties": false }, "confirm": { "type": "boolean", "const": true } }, "required": [ "action", "revision", "selection", "criteria", "scheduledBenchOn", "reportDueOn", "expiresAt", "trialCents", "shippingCents", "taxCents", "taxTreatment", "terms", "confirm" ], "additionalProperties": false }, "RevokeFinalOffer": { "type": "object", "properties": { "action": { "type": "string", "const": "revoke" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "offerId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "reason": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "action", "revision", "offerId", "reason" ], "additionalProperties": false }, "AcceptFinalOffer": { "type": "object", "properties": { "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "offerHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "confirm": { "type": "boolean", "const": true } }, "required": [ "revision", "offerHash", "confirm" ], "additionalProperties": false }, "FinalOfferCommand": { "oneOf": [ { "$ref": "#/components/schemas/IssueFinalOffer" }, { "$ref": "#/components/schemas/RevokeFinalOffer" } ] }, "QuotedOrderCheckout": { "type": "object", "properties": { "kind": { "const": "quoted_order" }, "quoteHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "executionHash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "amountCents": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "currency": { "const": "USD" }, "acceptedAt": { "type": "string", "format": "date-time" }, "termsVersion": { "const": "quoted-order-2026-10-20-v1" }, "terms": { "type": "object", "properties": { "cancellation": { "type": "string", "minLength": 1, "maxLength": 1500 }, "rework": { "type": "string", "minLength": 1, "maxLength": 1500 }, "shipmentRemedy": { "type": "string", "minLength": 1, "maxLength": 1500 }, "contactEmail": { "type": "string", "maxLength": 254, "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,}$" } }, "required": [ "cancellation", "rework", "shipmentRemedy", "contactEmail" ], "additionalProperties": false, "example": { "cancellation": "Cancel before preparation to stop the trial. After preparation starts, contact the lab to cancel remaining work. This pilot uses simulated payments; no money is collected or refunded.", "rework": "Clerical report errors are corrected with history retained. If agreed work is missing or a preparation is made incorrectly, contact us for a correction or a separately agreed remake. An unfavorable flavor result does not include another iteration.", "shipmentRemedy": "Shipped samples are for research only. Not for human or animal consumption. Report a missing, damaged, leaking or warm sample through your order or the contact below. We review the evidence and agree a replacement or other remedy before further work; no replacement is automatically booked.", "contactEmail": "peter@deconfound.com" } } }, "required": [ "kind", "quoteHash", "executionHash", "amountCents", "currency", "acceptedAt", "termsVersion", "terms" ], "description": "Public receipt of explicit consent to the saved recipe, complete quoted total and current trial terms. Returned on snapshot.checkout for the standard fully priced flow. It is not an operator final offer, work release or actual payment; private consenting identity and audit data are omitted." }, "FinalServiceOffer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "hash": { "type": "string" }, "status": { "enum": [ "issued", "superseded", "revoked", "accepted" ] }, "issuedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "originalBrief": { "type": "object", "properties": { "status": { "enum": [ "recorded", "not_recorded" ] }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "status", "text" ] }, "alternative": { "default": null, "anyOf": [ { "type": "object", "properties": { "description": { "type": "string", "minLength": 1, "maxLength": 1000 }, "reason": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "description", "reason" ], "additionalProperties": false }, { "type": "null" } ] }, "changes": { "type": "string" }, "scope": { "type": "object", "properties": { "recipes": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceRecipe" } }, "versions": { "type": "integer" }, "preparations": { "type": "integer" }, "iterationsIncluded": { "const": 1 }, "deliverables": { "type": "array", "items": { "enum": [ "photo", "taste", "ship" ] } }, "sampleCount": { "type": "integer" }, "sampleMassGPerVersion": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "destination": { "anyOf": [ { "type": "object", "properties": { "country": { "type": "string", "pattern": "^[A-Za-z]{2}$" }, "region": { "type": "string", "minLength": 2, "maxLength": 100 }, "postalCode": { "type": "string", "minLength": 3, "maxLength": 20 } }, "required": [ "country", "region", "postalCode" ], "additionalProperties": false }, { "type": "null" } ] }, "includes": { "type": "array", "items": { "type": "string" } }, "exclusions": { "type": "array", "items": { "type": "string" } } }, "required": [ "recipes", "versions", "preparations", "iterationsIncluded", "deliverables", "sampleCount", "sampleMassGPerVersion", "destination", "includes", "exclusions" ] }, "criteria": { "minItems": 2, "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "target": { "type": "string", "minLength": 1, "maxLength": 600 }, "method": { "type": "string", "enum": [ "maker_observation", "visual_observation", "instrument_reading" ] }, "metric": { "type": "string", "enum": [ "ph", "brix", "mass", "conductivity", "turbidity", "sensory" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] }, "id": { "type": "string", "format": "uuid" } }, "required": [ "id", "label", "target", "method" ], "additionalProperties": false } }, "price": { "type": "object", "properties": { "currency": { "const": "USD" }, "trialCents": { "type": "integer" }, "shippingCents": { "type": "integer" }, "taxCents": { "type": "integer" }, "taxTreatment": { "type": "string" }, "totalCents": { "type": "integer" } }, "required": [ "currency", "trialCents", "shippingCents", "taxCents", "taxTreatment", "totalCents" ] }, "reportDueOn": { "type": "string", "format": "date" }, "reportTimezone": { "const": "America/Los_Angeles" }, "terms": { "type": "object", "properties": { "cancellation": { "type": "string", "minLength": 1, "maxLength": 1500 }, "rework": { "type": "string", "minLength": 1, "maxLength": 1500 }, "shipmentRemedy": { "type": "string", "minLength": 1, "maxLength": 1500 }, "contactEmail": { "type": "string", "maxLength": 254, "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,}$" } }, "required": [ "cancellation", "rework", "shipmentRemedy", "contactEmail" ], "additionalProperties": false }, "work": { "type": "object", "properties": { "scheduledBenchOn": { "type": "string", "format": "date" }, "preparations": { "type": "integer" }, "estimatedBenchMinutes": { "type": "integer" }, "planningOnly": { "const": true } }, "required": [ "scheduledBenchOn", "preparations", "estimatedBenchMinutes", "planningOnly" ] }, "acceptance": { "anyOf": [ { "type": "object", "properties": { "acceptedAt": { "type": "string", "format": "date-time" }, "offerHash": { "type": "string" } }, "required": [ "acceptedAt", "offerHash" ] }, { "type": "null" } ] } }, "required": [ "id", "version", "hash", "status", "issuedAt", "expiresAt", "originalBrief", "alternative", "changes", "scope", "criteria", "price", "reportDueOn", "reportTimezone", "terms", "work", "acceptance" ] }, "OfferCriterion": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "target": { "type": "string", "minLength": 1, "maxLength": 600 }, "method": { "type": "string", "enum": [ "maker_observation", "visual_observation", "instrument_reading" ] }, "metric": { "type": "string", "enum": [ "ph", "brix", "mass", "conductivity", "turbidity", "sensory" ] }, "min": { "type": [ "number", "null" ] }, "max": { "type": [ "number", "null" ] }, "id": { "type": "string", "format": "uuid" } }, "required": [ "id", "label", "target", "method" ], "additionalProperties": false }, "FinalOfferView": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid" }, "revision": { "type": "integer" }, "current": { "anyOf": [ { "$ref": "#/components/schemas/FinalServiceOffer" }, { "type": "null" } ] }, "accepted": { "anyOf": [ { "$ref": "#/components/schemas/FinalServiceOffer" }, { "type": "null" } ] }, "offers": { "type": "array", "items": { "$ref": "#/components/schemas/FinalServiceOffer" } }, "canIssue": { "type": "boolean" }, "legacyAcceptance": { "anyOf": [ { "const": "not_recorded" }, { "type": "null" } ] }, "review": { "type": "object", "properties": { "eligible": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "eligible", "reasons" ] }, "lockedPrice": { "type": "object", "properties": { "currency": { "const": "USD" }, "trialCents": { "type": "integer" }, "shippingCents": { "type": "integer" }, "taxCents": { "type": "integer" }, "taxTreatment": { "type": "string" }, "totalCents": { "type": "integer" } }, "required": [ "currency", "trialCents", "shippingCents", "taxCents", "taxTreatment", "totalCents" ], "description": "Original saved order quote, when fully priced and unaccepted with the original scope. Same-scope offers must preserve these amounts." } }, "required": [ "orderId", "revision", "current", "accepted", "offers", "canIssue", "legacyAcceptance", "review" ] }, "BenchCapacityCommand": { "oneOf": [ { "type": "object", "properties": { "action": { "type": "string", "const": "configure" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "maxPreparationsPerDay": { "type": "integer", "minimum": 1, "maximum": 100 }, "maxBenchMinutesPerDay": { "type": "integer", "minimum": 15, "maximum": 1440 } }, "required": [ "action", "revision", "maxPreparationsPerDay", "maxBenchMinutesPerDay" ], "additionalProperties": false }, { "type": "object", "properties": { "action": { "type": "string", "const": "allocate" }, "orderId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "scheduledBenchOn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "note": { "type": "string", "minLength": 3, "maxLength": 1000 } }, "required": [ "action", "orderId", "scheduledBenchOn", "note" ], "additionalProperties": false } ] }, "SimpleOrderOutputCommand": { "type": "object", "properties": { "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "action": { "type": "string", "enum": [ "save", "complete" ] }, "notes": { "type": "string", "maxLength": 10000 }, "photos": { "default": [], "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "caption": { "default": "", "type": "string", "maxLength": 300 } }, "required": [ "id" ], "additionalProperties": false } }, "recipeResults": { "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "recipeId": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 10000 }, "photoIds": { "maxItems": 4, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "photosOmittedReason": { "type": "string", "maxLength": 1000 }, "evidence": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "batchId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "preparedAt": { "type": "string", "maxLength": 40 }, "actualBatchMassG": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 10000 }, { "type": "null" } ] }, "ingredients": { "maxItems": 40, "type": "array", "items": { "type": "object", "properties": { "ingredientId": { "type": "string", "minLength": 1, "maxLength": 100 }, "sourceId": { "type": "string", "maxLength": 100 }, "lot": { "type": "string", "maxLength": 200 }, "expiresOn": { "type": "string", "maxLength": 10 }, "actualMassG": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 10000 }, { "type": "null" } ] } }, "required": [ "ingredientId", "sourceId", "lot", "expiresOn", "actualMassG" ], "additionalProperties": false } }, "equipmentMethod": { "type": "string", "maxLength": 2000 }, "preparationPerformed": { "type": "string", "maxLength": 10000 }, "deviations": { "type": "string", "maxLength": 2000 }, "readinessConfirmed": { "type": "boolean" }, "tasting": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "unrecorded", "not_tasted", "tasted" ] }, "reason": { "type": "string", "maxLength": 2000 }, "notes": { "type": "string", "maxLength": 2000 }, "assessmentReference": { "type": "string", "maxLength": 2000 }, "approvedForTasting": { "type": "boolean" } }, "required": [ "status", "reason", "notes", "assessmentReference", "approvedForTasting" ], "additionalProperties": false } }, "required": [ "batchId", "preparedAt", "actualBatchMassG", "ingredients", "equipmentMethod", "preparationPerformed", "deviations", "readinessConfirmed", "tasting" ], "additionalProperties": false } } }, "required": [ "recipeId", "description", "photoIds" ], "additionalProperties": false } } }, "required": [ "revision", "action", "notes" ], "additionalProperties": false, "description": "Up to three recipeResults, four photos per recipe and twelve overall. action save permits incomplete observations. action complete requires every recipe exactly once, a nonempty condition description, a photo or photosOmittedReason, and evidence for every batch exactly once. Each evidence entry records exact ingredient/source IDs, lots and real unexpired use-by dates, actual masses, recovered batch mass, actual preparation and deviations, equipment/method check, readinessConfirmed, and explicit tasting status. not_tasted requires a reason; tasted requires actual notes, an assessment reference and approvedForTasting. Current product/application/dose/allergen and process qualification must cover actual amounts. Unknown evidence cannot grant physical completion. Legacy notes-only requests may still save drafts but cannot complete; historical publications remain readable. IDs and photo ownership/batch associations are validated against the actual order." }, "SimpleRecipeResult": { "type": "object", "properties": { "recipeId": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 10000 }, "photoIds": { "maxItems": 4, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "photosOmittedReason": { "type": "string", "maxLength": 1000 }, "evidence": { "maxItems": 6, "type": "array", "items": { "type": "object", "properties": { "batchId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "preparedAt": { "type": "string", "maxLength": 40 }, "actualBatchMassG": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0, "maximum": 10000 }, { "type": "null" } ] }, "ingredients": { "maxItems": 40, "type": "array", "items": { "type": "object", "properties": { "ingredientId": { "type": "string", "minLength": 1, "maxLength": 100 }, "sourceId": { "type": "string", "maxLength": 100 }, "lot": { "type": "string", "maxLength": 200 }, "expiresOn": { "type": "string", "maxLength": 10 }, "actualMassG": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 10000 }, { "type": "null" } ] } }, "required": [ "ingredientId", "lot", "expiresOn", "actualMassG" ], "additionalProperties": false } }, "equipmentMethod": { "type": "string", "maxLength": 2000 }, "preparationPerformed": { "type": "string", "maxLength": 10000 }, "deviations": { "type": "string", "maxLength": 2000 }, "readinessConfirmed": { "type": "boolean" }, "tasting": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "unrecorded", "not_tasted", "tasted" ] }, "reason": { "type": "string", "maxLength": 2000 }, "notes": { "type": "string", "maxLength": 2000 }, "assessmentReference": { "type": "string", "maxLength": 2000 }, "approvedForTasting": { "type": "boolean" } }, "required": [ "status", "reason", "notes", "assessmentReference", "approvedForTasting" ], "additionalProperties": false } }, "required": [ "batchId", "preparedAt", "actualBatchMassG", "ingredients", "equipmentMethod", "preparationPerformed", "deviations", "readinessConfirmed", "tasting" ], "additionalProperties": false } } }, "required": [ "recipeId", "description", "photoIds" ], "additionalProperties": false, "description": "Operator-recorded sample condition, photo associations and actual preparation evidence. recipeId identifies snapshot.recipes[].id; photoIds resolve through output.photos. Evidence covers every batch, exact product/lot/use-by, actual amounts and recovered mass, equipment/method, actual preparation, deviations and explicit tasted or not_tasted status. Historical published reports may omit evidence. Source IDs are private and omitted from customer responses." }, "SimpleOrderOutput": { "type": "object", "properties": { "notes": { "type": "string", "maxLength": 10000 }, "photos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "caption": { "type": "string", "maxLength": 300 }, "url": { "type": "string" } }, "required": [ "id", "caption", "url" ] }, "maxItems": 12 }, "recipeResults": { "type": "array", "items": { "$ref": "#/components/schemas/SimpleRecipeResult" }, "maxItems": 3, "description": "Optional for compatibility with earlier notes/photo reports. Each entry describes one recipe; no observation should be inferred for an absent entry." }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "notes", "photos", "completedAt", "updatedAt" ] }, "SimpleOrderOutputView": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid" }, "revision": { "type": "integer" }, "fulfillmentStatus": { "type": "string" }, "output": { "anyOf": [ { "$ref": "#/components/schemas/SimpleOrderOutput" }, { "type": "null" } ] } }, "required": [ "orderId", "revision", "fulfillmentStatus", "output" ] }, "OperatorOrderOutputView": { "type": "object", "properties": { "orderId": { "type": "string", "format": "uuid" }, "revision": { "type": "integer" }, "fulfillmentStatus": { "type": "string" }, "output": { "anyOf": [ { "$ref": "#/components/schemas/SimpleOrderOutput" }, { "type": "null" } ] }, "publishedOutput": { "anyOf": [ { "$ref": "#/components/schemas/SimpleOrderOutput" }, { "type": "null" } ] }, "readiness": { "type": "array", "items": { "type": "object", "properties": { "recipeId": { "type": "string" }, "qualified": { "type": "boolean" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "ingredientId": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ] } } }, "required": [ "recipeId", "qualified", "issues" ] } } }, "required": [ "orderId", "revision", "fulfillmentStatus", "output", "publishedOutput", "readiness" ] }, "CreationReceipt": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "createdAt": { "type": "string", "format": "date-time" }, "links": { "type": "object", "properties": { "self": { "type": "string" } }, "required": [ "self" ] } }, "required": [ "id", "createdAt", "links" ], "description": "Stable receipt for a write-only key. Contains no evolving request, status, revision, recipe or evidence. Read the linked resource using its read scope." } } } }