{ "openapi": "3.1.0", "info": { "title": "Maglev Manufacturing API", "version": "1.1.3", "description": "Connect existing agents to manufacturing: capabilities, interviews, factory knowledge, lifecycle stages, projects and reviewed actions. Sandbox cannot send to factories. Live deliveries require explicit approval; a saved catalog run is not supplier dispatch.", "contact": { "name": "Maglev", "url": "https://trymaglev.com", "email": "hello@trymaglev.com" } }, "servers": [ { "url": "https://app.trymaglev.com/api/v1" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "keys" }, { "name": "network", "description": "Factories, what they told us, and interactions" }, { "name": "knowledge" }, { "name": "lifecycle" }, { "name": "projects" }, { "name": "actions" }, { "name": "deliveries", "description": "Outbound messages behind approval" }, { "name": "shipping" }, { "name": "compliance" }, { "name": "catalog", "description": "Interview backed capabilities" }, { "name": "quotes", "description": "Managed supplier requests and the quote versions linked to them, read only" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "maglev_test_… or maglev_live_…" }, "SessionCookie": { "type": "apiKey", "in": "cookie", "name": "maglev_session", "description": "Existing signed-in Maglev workspace session. Each operation checks the required organization membership or owner role; live key issuance requires an organization owner." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": {} }, "required": [ "code", "message" ] }, "requestId": { "type": "string" } }, "required": [ "error", "requestId" ] }, "Stage": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "phase": { "type": "string", "description": "discovery, engineering, pre_production, production, delivery or compliance" }, "order": { "type": "integer" }, "description": { "type": "string" }, "inputs": { "type": "array", "items": { "type": "string" } }, "outputs": { "type": "array", "items": { "type": "string" } }, "typicalDurationDays": { "anyOf": [ { "type": "integer", "description": "Only when a Maglev document states one" }, { "type": "null" } ] }, "typicalCostUsd": { "anyOf": [ { "type": "object", "properties": { "min": { "type": "number" }, "max": { "type": "number" } } }, { "type": "null" } ] }, "maglevRole": { "type": "string" }, "availability": { "type": "string", "description": "available, coordinated or planned" }, "actionKinds": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "string", "description": "bay2bay repo paths" } } } }, "FactoryListItem": { "type": "object", "properties": { "id": { "type": "string", "description": "uuid" }, "directoryId": { "anyOf": [ { "type": "string", "description": "Stable directory id such as mfg-sz-robotics-001" }, { "type": "null" } ] }, "nameEn": { "type": "string" }, "nameZh": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "processes": { "type": "array", "items": { "type": "string" } }, "specialty": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "capabilities": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "moqText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "leadTimeText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minQuantityByProcess": { "type": "object", "properties": {} }, "englishCapability": { "type": "string", "description": "yes, some, no or unknown" }, "startupFriendly": { "type": "string", "description": "yes, no or unknown" }, "exportedToUs": { "type": "string", "description": "yes, no or unknown" }, "answeredUs": { "type": "boolean", "description": "The factory has answered Maglev directly" }, "lastAnsweredAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "confidence": { "type": "string", "description": "verified, reported or unverified" }, "certifications": { "type": "array", "items": { "type": "string" } }, "entityType": { "type": "string" }, "dataIssues": { "type": "array", "items": { "type": "string" } }, "profileStatus": { "type": "string" } } }, "Project": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "product": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "targetQuantity": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "stage": { "type": "string", "description": "prototype, first_batch, second_batch or later" }, "markets": { "type": "array", "items": { "type": "string" } }, "intake": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "manufacturingIntent": { "anyOf": [ { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1 }, "current": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "samples", "pilot", "production", "unknown" ] }, "quantity": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 10000000 }, { "type": "null" } ] }, "unit": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] }, "configuration": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] }, "revision": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] }, "confirmation": { "type": "string", "enum": [ "unconfirmed", "caller_confirmed" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "caller", "file", "interview" ] }, "reference": { "type": "string", "minLength": 1, "maxLength": 800 }, "quote": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] } }, "required": [ "kind", "reference", "quote" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "purpose", "quantity", "unit", "configuration", "revision", "confirmation", "source" ], "additionalProperties": false }, "plannedPilot": { "anyOf": [ { "type": "object", "properties": { "quantity": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 10000000 }, { "type": "null" } ] }, "unit": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] }, "period": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "caller", "file", "interview" ] }, "reference": { "type": "string", "minLength": 1, "maxLength": 800 }, "quote": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] } }, "required": [ "kind", "reference", "quote" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "quantity", "unit", "period", "source" ], "additionalProperties": false }, { "type": "null" } ] }, "forecast": { "anyOf": [ { "type": "object", "properties": { "quantity": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 10000000 }, { "type": "null" } ] }, "unit": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] }, "period": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "caller", "file", "interview" ] }, "reference": { "type": "string", "minLength": 1, "maxLength": 800 }, "quote": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] } }, "required": [ "kind", "reference", "quote" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "quantity", "unit", "period", "source" ], "additionalProperties": false }, { "type": "null" } ] }, "requirements": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "location", "quality", "material", "inspection", "deadline", "other" ] }, "detail": { "type": "string", "minLength": 1, "maxLength": 800 }, "strength": { "type": "string", "enum": [ "hard", "preference" ] }, "confirmation": { "type": "string", "enum": [ "unconfirmed", "caller_confirmed" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "caller", "file", "interview" ] }, "reference": { "type": "string", "minLength": 1, "maxLength": 800 }, "quote": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] } }, "required": [ "kind", "reference", "quote" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "kind", "detail", "strength", "confirmation", "source" ], "additionalProperties": false } }, "priorities": { "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "quality", "price", "lead_time", "scale", "location" ] } }, "prioritySource": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "caller", "file", "interview" ] }, "reference": { "type": "string", "minLength": 1, "maxLength": 800 }, "quote": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] } }, "required": [ "kind", "reference", "quote" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "schemaVersion", "current", "plannedPilot", "forecast", "requirements", "priorities", "prioritySource" ], "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": {} }, "contextVersion": { "type": "string", "description": "Content fingerprint used for intent edits and RFQ approval" }, "status": { "type": "string" }, "createdAt": { "type": "string" } } }, "Action": { "type": "object", "properties": { "id": { "type": "string" }, "projectId": { "type": "string" }, "kind": { "type": "string" }, "stageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "availability": { "type": "string" }, "status": { "type": "string", "description": "queued, running, draft_ready, awaiting_approval, approved, sent, done or failed" }, "input": { "type": "object", "properties": {} }, "output": { "anyOf": [ { "$ref": "#/components/schemas/ActionOutput" }, { "type": "null" } ], "description": "Null until a result is saved. Read the kind-specific value at action.output.result." }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "agentRunId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "taskId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" } } }, "ActionOutput": { "type": "object", "properties": { "draft": { "type": "boolean", "const": true }, "note": { "type": "string" }, "result": { "type": "object", "description": "Kind-specific result; validate against the output schema in x-action-kinds." } }, "required": [ "draft", "note", "result" ], "description": "Saved result envelope. The action kind output schema describes result, not this envelope." }, "ActionListEntry": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/Action" }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/DeliverySummary" } } }, "required": [ "action", "deliveries" ] }, "DeliverySummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "channel": { "type": "string" }, "factoryId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "toName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "status", "channel", "factoryId", "toName", "subject" ] }, "TaskSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "title", "status" ] }, "Delivery": { "type": "object", "properties": { "id": { "type": "string" }, "actionId": { "type": "string" }, "channel": { "type": "string", "description": "email or wechat" }, "factoryId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "toName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "toAddress": { "anyOf": [ { "type": "string", "description": "Resolved from the factory at approval time, never supplied by the caller in live mode" }, { "type": "null" } ] }, "cc": { "type": "array", "items": { "type": "string", "description": "Both Maglev founders, always" } }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyEn": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyZh": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "description": "draft, approved, queued, sending, delivery_unknown, delivery_failed, sent, rejected or needs_contact" }, "transport": { "anyOf": [ { "type": "string", "description": "resend, resend_pending, outbox or manual" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sentAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "RfqSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "projectName": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "sent", "closed" ] }, "anonymised": { "type": "boolean", "description": "The buyer is anonymised to the supplier in the managed request" }, "scope": { "type": "string" }, "sourcingModel": { "type": "string" }, "runKind": { "type": "string" }, "priority": { "type": "string" }, "drawingsStatus": { "type": "string" }, "toolOwnershipRequired": { "type": "boolean" }, "bomId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "lineIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "fileIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "requested": { "type": "object", "properties": { "quantities": { "type": "array", "items": { "type": "integer" } }, "targetUnitPrice": { "anyOf": [ { "type": "string", "description": "Decimal string; null when the buyer set no target" }, { "type": "null" } ] }, "currency": { "type": "string", "description": "Stored currency" }, "currencyAtColumnDefault": { "type": "boolean", "description": "True only when the stored value is indistinguishable from the USD column default: the RFQ was created in the Maglev workspace, whose form cannot tell a chosen USD from an unstated one, and still stores USD. False on an RFQ published through POST /actions/{id}/publication, which requires the currency in the reviewed selection and hashes it into reviewSha256, so a chosen USD is a declared currency there." }, "incoterm": { "type": "string", "description": "Stored Incoterm" }, "incotermAtColumnDefault": { "type": "boolean", "description": "True only when the stored value is indistinguishable from the EXW column default: a workspace-created RFQ still storing EXW. False on an RFQ published through POST /actions/{id}/publication, which requires the Incoterm in the reviewed selection and hashes it into reviewSha256." }, "namedPlace": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "deliverTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quoteBy": { "anyOf": [ { "type": "string", "description": "ISO date; null when no deadline was recorded" }, { "type": "null" } ] } }, "required": [ "quantities", "targetUnitPrice", "currency", "currencyAtColumnDefault", "incoterm", "incotermAtColumnDefault", "namedPlace", "deliverTo", "quoteBy" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "projectId", "projectName", "title", "status", "anonymised", "scope", "sourcingModel", "runKind", "priority", "drawingsStatus", "toolOwnershipRequired", "bomId", "lineIds", "fileIds", "requested", "createdAt", "updatedAt" ] }, "RfqInvitation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "factoryId": { "type": "string", "format": "uuid" }, "factoryNameEn": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "factoryNameZh": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "factoryCity": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "threadId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "invited", "viewed", "declined", "quoted", "accepted", "rejected" ] }, "declined": { "type": "boolean", "description": "A recorded decline, which is not the same as an absent invitation" }, "declinedReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "viewedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" }, "latestQuoteVersion": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "publishedRevisions": { "type": "array", "items": { "type": "object", "properties": { "revision": { "type": "integer" }, "reviewSha256": { "type": "string" }, "publishedAt": { "type": "string", "format": "date-time" } }, "required": [ "revision", "reviewSha256", "publishedAt" ] }, "description": "The revisions of this request this factory was actually a recipient of, oldest first. Empty on an RFQ created in the Maglev workspace. A factory added by a later revision does not list revisions it was never sent." }, "currentRevision": { "anyOf": [ { "type": "integer", "description": "The newest revision this factory was sent; null when the RFQ was not published through the API" }, { "type": "null" } ] }, "quotes": { "type": "array", "items": { "$ref": "#/components/schemas/SupplierQuote" }, "description": "Newest version first; earlier versions are retained" } }, "required": [ "id", "factoryId", "factoryNameEn", "factoryNameZh", "factoryCity", "threadId", "status", "declined", "declinedReason", "viewedAt", "createdAt", "updatedAt", "latestQuoteVersion", "publishedRevisions", "currentRevision", "quotes" ] }, "SupplierQuote": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "description": "Versions are per invitation. A revision adds a row; it never replaces the earlier one." }, "status": { "type": "string", "enum": [ "submitted", "revised", "accepted", "declined" ] }, "provenance": { "type": "object", "properties": { "source": { "type": "string", "const": "supplier_portal_submission" }, "modelExtracted": { "type": "boolean", "const": false }, "submittedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "submittedByUserId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "quoteReference": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quoteDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "source", "modelExtracted", "submittedAt", "submittedByUserId", "quoteReference", "quoteDate" ] }, "answersRevision": { "anyOf": [ { "type": "integer", "description": "The revision of the request that was in force when the supplier submitted this quote. Null on an RFQ that was never published through the API, and null for a quote that predates every published revision, in which case supersededByRevision names the current one." }, { "type": "null" } ] }, "supersededByRevision": { "anyOf": [ { "type": "integer", "description": "The current revision when it is later than answersRevision, so this quote was priced against terms that have since been corrected; null when this quote answers the current revision" }, { "type": "null" } ] }, "commercial": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency of the quoted prices.", "enum": [ "USD", "CNY" ] }, "currencyAtColumnDefault": { "type": "boolean", "description": "True when the stored value is still USD, the column default, so it cannot be read as a currency the supplier declared." }, "incoterm": { "type": "string", "enum": [ "EXW", "FCA", "CPT", "CIP", "DAP", "DPU", "DDP", "FAS", "FOB", "CFR", "CIF" ] }, "incotermAtColumnDefault": { "type": "boolean", "description": "True when the stored value is still EXW, the column default, so it cannot be read as a trade term the supplier declared." }, "namedPlace": { "anyOf": [ { "type": "string", "description": "The place the Incoterm is quoted to; null when none was recorded" }, { "type": "null" } ] }, "priceBreaks": { "type": "array", "items": { "type": "object", "properties": { "quantity": { "type": "number" }, "unitPrice": { "type": "number" } }, "required": [ "quantity", "unitPrice" ] }, "description": "Quantity breaks exactly as submitted. Empty when the supplier quoted no unit price." }, "quoteUnit": { "type": "string", "description": "What one unit of priceBreaks.unitPrice buys.", "enum": [ "piece", "set", "unknown" ] }, "taxIncluded": { "type": "string", "description": "Whether the quoted price includes tax.", "enum": [ "included", "excluded", "unknown" ] }, "moq": { "anyOf": [ { "type": "integer", "description": "Minimum order quantity; null when none was stated" }, { "type": "null" } ] }, "moqDriver": { "anyOf": [ { "type": "string", "description": "Why that minimum applies, in the supplier's words; null when not stated" }, { "type": "null" } ] }, "toolingCost": { "anyOf": [ { "type": "string", "description": "Decimal string; null when no tooling cost was stated" }, { "type": "null" } ] }, "toolingType": { "type": "string", "description": "What tooling the price assumes.", "enum": [ "none", "rapid_aluminum", "steel_bridge", "production_steel", "other" ] }, "toolingShotLife": { "anyOf": [ { "type": "integer", "description": "Shots the tool is quoted to last; null when not stated" }, { "type": "null" } ] }, "toolingLeadDays": { "anyOf": [ { "type": "integer", "description": "Calendar days to cut the tool; null when not stated" }, { "type": "null" } ] }, "moldOwnership": { "type": "string", "description": "Who owns the tool once it is paid for.", "enum": [ "customer", "factory", "unknown" ] }, "retoolCost": { "anyOf": [ { "type": "string", "description": "Decimal string; null when no retool price was stated" }, { "type": "null" } ] }, "sampleCost": { "anyOf": [ { "type": "string", "description": "Decimal string; null when no sample price was stated" }, { "type": "null" } ] }, "sampleLeadDays": { "anyOf": [ { "type": "integer", "description": "Calendar days to a sample; null when not stated" }, { "type": "null" } ] }, "productionLeadDays": { "anyOf": [ { "type": "integer", "description": "Calendar days for the production run; null when not stated" }, { "type": "null" } ] }, "leadTimeClockStartsOn": { "type": "string", "description": "What starts the lead time clock. Two quotes with the same lead days are not comparable when this differs.", "enum": [ "po", "deposit_cleared", "sample_approved", "material_arrival", "artwork_confirmed", "unknown" ] }, "paymentTerms": { "anyOf": [ { "type": "string", "description": "Payment terms in the supplier's own words; null when none were stated" }, { "type": "null" } ] }, "paymentMethod": { "type": "string", "description": "How payment is made.", "enum": [ "tt", "lc_at_sight", "alibaba_trade_assurance", "escrow", "other", "unknown" ] }, "depositPct": { "anyOf": [ { "type": "string", "description": "Decimal string, percent of order value; null when no deposit was stated" }, { "type": "null" } ] }, "balanceTrigger": { "type": "string", "description": "What releases the balance payment.", "enum": [ "before_shipment", "against_bl_copy", "against_passed_inspection", "on_delivery", "other", "unknown" ] }, "fixturesPaidBy": { "type": "string", "description": "Who pays for test and assembly fixtures.", "enum": [ "factory", "customer", "shared", "unknown" ] }, "inspectionReportPaidBy": { "type": "string", "description": "Who pays for the third party inspection report.", "enum": [ "factory", "customer", "shared", "unknown" ] }, "exclusions": { "type": "array", "items": { "type": "string" }, "description": "What the quoted price excludes. Empty when nothing was listed, which is not the same as nothing being excluded." }, "nreLines": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "category": { "type": "string" }, "amount": { "type": "number" }, "deliverable": { "type": "string" } }, "required": [ "label", "category", "amount" ] }, "description": "Non recurring engineering lines as submitted. Empty when none were listed." }, "revisionClause": { "anyOf": [ { "type": "string", "description": "What a later drawing or specification change costs; null when not stated" }, { "type": "null" } ] } }, "required": [ "currency", "currencyAtColumnDefault", "incoterm", "incotermAtColumnDefault", "namedPlace", "priceBreaks", "quoteUnit", "taxIncluded", "moq", "moqDriver", "toolingCost", "toolingType", "toolingShotLife", "toolingLeadDays", "moldOwnership", "retoolCost", "sampleCost", "sampleLeadDays", "productionLeadDays", "leadTimeClockStartsOn", "paymentTerms", "paymentMethod", "depositPct", "balanceTrigger", "fixturesPaidBy", "inspectionReportPaidBy", "exclusions", "nreLines", "revisionClause" ] }, "validity": { "type": "object", "properties": { "validUntil": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "valid", "expired", "unknown" ] } }, "required": [ "validUntil", "state" ] }, "maglevFee": { "anyOf": [ { "type": "string", "description": "Maglev's own line, decimal string. Buyer audience only; a supplier organization key is refused before any read." }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string", "description": "Supplier commercial notes as submitted. Buyer audience only." }, { "type": "null" } ] }, "notesTranslated": { "anyOf": [ { "type": "string", "description": "Machine translation of notes; null when none was produced. Buyer audience only." }, { "type": "null" } ] }, "dfmNotes": { "anyOf": [ { "type": "string", "description": "Supplier design-for-manufacture notes as submitted. Buyer audience only." }, { "type": "null" } ] }, "dfmNotesTranslated": { "anyOf": [ { "type": "string", "description": "Machine translation of dfmNotes; null when none was produced. Buyer audience only." }, { "type": "null" } ] }, "fileIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Files the supplier attached to this quote version" } }, "required": [ "id", "version", "status", "provenance", "answersRevision", "supersededByRevision", "commercial", "validity", "maglevFee", "notes", "notesTranslated", "dfmNotes", "dfmNotesTranslated", "fileIds" ] }, "Facts": { "type": "object", "properties": { "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "process": { "anyOf": [ { "type": "string", "enum": [ "cnc", "pcba", "injection_molding", "sheet_metal", "3d_printing", "wire_harness", "assembly", "testing" ] }, { "type": "null" } ] }, "materials": { "type": "array", "items": { "type": "string" } }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minQuantity": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "unitPriceUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "setupPriceUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "leadTimeDays": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "toleranceMm": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "certifications": { "type": "array", "items": { "type": "string" } }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quantity": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "quote": { "type": "string" } }, "required": [ "field", "quote" ] } } }, "required": [ "company", "process", "materials", "country", "minQuantity", "unitPriceUsd", "setupPriceUsd", "leadTimeDays", "toleranceMm", "certifications", "description", "quantity", "evidence" ] }, "Capability": { "type": "object", "properties": { "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "process": { "anyOf": [ { "type": "string", "enum": [ "cnc", "pcba", "injection_molding", "sheet_metal", "3d_printing", "wire_harness", "assembly", "testing" ] }, { "type": "null" } ] }, "materials": { "type": "array", "items": { "type": "string" } }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minQuantity": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "unitPriceUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "setupPriceUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "leadTimeDays": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "toleranceMm": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "certifications": { "type": "array", "items": { "type": "string" } }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quantity": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "quote": { "type": "string" } }, "required": [ "field", "quote" ] } }, "id": { "type": "string" }, "status": { "type": "string" }, "source": { "type": "string" }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] } }, "required": [ "company", "process", "materials", "country", "minQuantity", "unitPriceUsd", "setupPriceUsd", "leadTimeDays", "toleranceMm", "certifications", "description", "quantity", "evidence", "id", "status", "source", "mode" ] }, "CapabilityRecord": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "owner": { "type": "string" }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "createdAt": { "type": "string", "format": "date-time" }, "interviewId": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "data": { "$ref": "#/components/schemas/Facts" }, "reviewedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "owner", "mode", "createdAt", "interviewId", "status", "data", "reviewedAt" ] }, "Estimate": { "type": "object", "properties": { "currency": { "const": "USD", "type": "string" }, "quantity": { "type": "integer" }, "factoryTotalUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "maglevFeeUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "shippingAndTaxesUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "binding": { "const": false, "type": "boolean" } }, "required": [ "currency", "quantity", "factoryTotalUsd", "maglevFeeUsd", "shippingAndTaxesUsd", "binding" ] }, "Match": { "type": "object", "properties": { "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "process": { "anyOf": [ { "type": "string", "enum": [ "cnc", "pcba", "injection_molding", "sheet_metal", "3d_printing", "wire_harness", "assembly", "testing" ] }, { "type": "null" } ] }, "materials": { "type": "array", "items": { "type": "string" } }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minQuantity": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "unitPriceUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "setupPriceUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "leadTimeDays": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "toleranceMm": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "certifications": { "type": "array", "items": { "type": "string" } }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quantity": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "quote": { "type": "string" } }, "required": [ "field", "quote" ] } }, "id": { "type": "string" }, "status": { "type": "string" }, "source": { "type": "string" }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "estimate": { "$ref": "#/components/schemas/Estimate" }, "reasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "company", "process", "materials", "country", "minQuantity", "unitPriceUsd", "setupPriceUsd", "leadTimeDays", "toleranceMm", "certifications", "description", "quantity", "evidence", "id", "status", "source", "mode", "estimate", "reasons" ] }, "Interview": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "owner": { "type": "string" }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "createdAt": { "type": "string", "format": "date-time" }, "kind": { "type": "string", "enum": [ "founder", "manufacturer" ] }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string" } }, "required": [ "role", "content" ] } }, "extraction": { "anyOf": [ { "$ref": "#/components/schemas/Facts" }, { "type": "null" } ] }, "version": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "owner", "mode", "createdAt", "kind", "messages", "extraction", "version", "updatedAt" ] }, "RunInput": { "type": "object", "properties": { "capabilityId": { "type": "string" }, "input": { "type": "object", "properties": { "quantity": { "type": "integer" }, "specification": { "type": "string" } }, "required": [ "quantity", "specification" ] } }, "required": [ "capabilityId", "input" ] }, "RunOutput": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "sandbox_complete", "quote_review_required" ] }, "capabilityId": { "type": "string" }, "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quantity": { "type": "integer" }, "factoryEstimateUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "maglevFeeUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "shippingAndTaxesUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "leadTimeDays": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "orderPlaced": { "type": "boolean", "const": false }, "nextSteps": { "type": "array", "items": { "type": "string" } }, "events": { "type": "array", "items": { "type": "object", "properties": { "step": { "type": "string" }, "status": { "type": "string" } }, "required": [ "step", "status" ] } } }, "required": [ "status", "capabilityId", "company", "quantity", "factoryEstimateUsd", "maglevFeeUsd", "shippingAndTaxesUsd", "leadTimeDays", "orderPlaced", "nextSteps", "events" ] }, "Run": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "owner": { "type": "string" }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "createdAt": { "type": "string", "format": "date-time" }, "idempotencyKey": { "type": "string" }, "inputHash": { "type": "string" }, "input": { "$ref": "#/components/schemas/RunInput" }, "output": { "$ref": "#/components/schemas/RunOutput" } }, "required": [ "id", "owner", "mode", "createdAt", "idempotencyKey", "inputHash", "input", "output" ] }, "KeyInfo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "prefix", "mode", "expiresAt", "revokedAt", "createdAt" ] } } }, "paths": { "/health": { "get": { "summary": "Service health, what an interview turn would actually do right now, and the endpoint families available.", "description": "Public health probe that reaches the key store. Returns supported endpoint families and interviewer configuration or recent degraded state; neither establishes a successful model completion or supplier execution.", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "ok" }, "version": { "type": "string" }, "interviewer": { "type": "string", "enum": [ "model", "guided", "degraded" ] }, "baseUrl": { "type": "string" }, "families": { "type": "array", "items": { "type": "string" } }, "requestId": { "type": "string" } }, "required": [ "status", "version", "interviewer", "baseUrl", "families", "requestId" ] } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get_health" } }, "/openapi.json": { "get": { "summary": "This document.", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/keys": { "get": { "summary": "List the signed in organisation's keys (browser session).", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "signedIn": { "const": false }, "keys": { "type": "array", "items": { "$ref": "#/components/schemas/KeyInfo" } }, "requestId": { "type": "string" } }, "required": [ "signedIn", "keys", "requestId" ] }, { "type": "object", "properties": { "signedIn": { "const": true }, "organisation": { "type": "string" }, "keys": { "type": "array", "items": { "$ref": "#/components/schemas/KeyInfo" } }, "requestId": { "type": "string" } }, "required": [ "signedIn", "organisation", "keys", "requestId" ] } ] } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get_keys", "description": "Uses the browser session. An unauthenticated call returns signedIn false and an empty key list. No secret is returned." }, "post": { "summary": "Issue a key. Sandbox keys are anonymous and live one day; live keys need a signed in organisation owner and live 90 days.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "name": { "type": "string" } }, "required": [ "mode" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string" }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "scopes": { "type": "array", "items": { "type": "string" } }, "note": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "id", "key", "mode", "expiresAt", "scopes", "note", "requestId" ] } } } }, "400": { "description": "Invalid input or missing idempotency header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid key or missing sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "string" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "post_keys", "description": "Sandbox issuance is unauthenticated and rate-limited. Live issuance requires a signed-in organization owner session in the console. Scopes are assigned from key mode and organization role and enforced per operation. Custom caller-selected scopes are not supported by this endpoint." } }, "/keys/{id}": { "delete": { "summary": "Revoke a key: the current key with a bearer token, or any of the organisation's keys with an owner session.", "security": [ { "BearerAuth": [] }, { "SessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean", "const": true }, "requestId": { "type": "string" } }, "required": [ "revoked", "requestId" ] } } } }, "400": { "description": "Invalid input or missing idempotency header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid key or missing sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Endpoint or record unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "string" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "delete_keys_id", "description": "A bearer key can revoke only itself. A signed-in organization owner can revoke a key belonging to the organization." } }, "/me": { "get": { "summary": "The calling key: mode, organisation kind and effective scopes.", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "organisationKind": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "requestId": { "type": "string" } }, "required": [ "id", "name", "mode", "expiresAt", "organisationKind", "scopes", "requestId" ] } } } }, "401": { "description": "Invalid key or missing sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "string" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get_me" } }, "/auth/device": { "post": { "summary": "Start a short-lived browser connection for Maglev CLI. No API key is created until an organization owner explicitly reviews and approves the matching terminal code.", "description": "JSON Maglev pairing protocol inspired by device authorization; not an OAuth/OIDC interoperability endpoint. Codes expire after ten minutes. Keep deviceCode private; only userCode enters the browser URL. Only the fixed Maglev application URL is returned in production. Ten starts per IP per hour.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "client": { "type": "string", "const": "maglev-cli" }, "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] } }, "required": [ "client", "name", "mode" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceCode": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "userCode": { "type": "string", "pattern": "^[A-HJ-NP-Z2-9]{4}-[A-HJ-NP-Z2-9]{4}$" }, "verificationUri": { "type": "string", "format": "uri" }, "verificationUriComplete": { "type": "string", "format": "uri" }, "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))$" }, "expiresIn": { "type": "number", "const": 600 }, "interval": { "type": "number", "const": 5 }, "note": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "deviceCode", "userCode", "verificationUri", "verificationUriComplete", "expiresAt", "expiresIn", "interval", "note", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/device/poll": { "post": { "summary": "Check the same browser connection after its polling interval. Receives the same temporary API key after approval, including after a lost response.", "description": "Wait at least interval seconds. HTTP 400 authorization_pending means wait; slow_down returns an increased details.interval (up to thirty seconds), persisted by the server. access_denied, expired_token, issuance_limit and device_consumed are terminal outcomes. The temporary key expires with the ten-minute request. Save it privately and acknowledge using that key before expiry; acknowledgement extends its normal lifetime. Owner/session/organization/scope changes or revoked keys cannot silently mint a replacement.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceCode": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": [ "deviceCode" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "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)$" }, "key": { "type": "string", "pattern": "^maglev_(test|live)_[A-Za-z0-9_-]{43}$" }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "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))$" }, "scopes": { "type": "array", "items": { "type": "string" } }, "acknowledgementRequired": { "type": "boolean", "const": true }, "keyLifetimeDays": { "anyOf": [ { "type": "number", "const": 1 }, { "type": "number", "const": 90 } ] }, "requestId": { "type": "string" } }, "required": [ "id", "key", "mode", "expiresAt", "scopes", "acknowledgementRequired", "keyLifetimeDays", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/device/acknowledge": { "post": { "summary": "Confirm that this terminal privately saved its own new key; requires that exact key as Bearer authorization.", "description": "Call only after durable local credential persistence. Extends live keys to ninety days or sandbox keys to one day from key creation. Same-request acknowledgement is replayable; it never issues another key. After acknowledgement device polling cannot retrieve the token again. Revocation remains available through DELETE /keys/{id}.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceCode": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": [ "deviceCode" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "acknowledged": { "type": "boolean", "const": true }, "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)$" }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "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))$" }, "requestId": { "type": "string" } }, "required": [ "acknowledged", "id", "mode", "expiresAt", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/auth/device/cancel": { "post": { "summary": "Cancel an unacknowledged terminal request using its private deviceCode. Any issued temporary key is revoked atomically.", "description": "Does not revoke an acknowledged installation; use the ordinary key revocation endpoint for that. Repeating cancellation is safe.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceCode": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": [ "deviceCode" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "cancelled": { "const": true }, "requestId": { "type": "string" } }, "required": [ "cancelled", "requestId" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/discover": { "post": { "summary": "Rank interview backed capabilities for a request. Sandbox data is synthetic.", "x-scope": "discover", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 500 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 10000000 }, "optimize": { "type": "string", "enum": [ "cost", "speed" ] }, "process": { "type": "string", "enum": [ "cnc", "pcba", "injection_molding", "sheet_metal", "3d_printing", "wire_harness", "assembly", "testing" ] }, "material": { "type": "string" }, "country": { "type": "string" }, "maxLeadTimeDays": { "type": "integer", "minimum": 1 }, "maxUnitPriceUsd": { "type": "number", "exclusiveMinimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 30 } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Match" } }, "count": { "type": "integer" }, "pricingNote": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "mode", "results", "count", "pricingNote", "requestId" ] } } } }, "400": { "description": "Invalid input or missing idempotency header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid key or missing sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "string" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "post_discover" } }, "/inspect": { "post": { "summary": "One capability with its input schema and non binding pricing.", "x-scope": "inspect", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "capabilityId": { "type": "string", "maxLength": 100 } }, "required": [ "capabilityId" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "capability": { "$ref": "#/components/schemas/Capability" }, "inputSchema": { "type": "object", "properties": { "type": { "type": "string" }, "required": { "type": "array", "items": { "type": "string" } }, "properties": { "type": "object", "additionalProperties": { "type": "object" } } }, "required": [ "type", "required", "properties" ] }, "execution": { "type": "string" }, "requiredFiles": { "type": "array", "items": { "type": "string" } }, "pricing": { "type": "object", "properties": { "currency": { "type": "string", "const": "USD" }, "unitPrice": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "setupPrice": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "maglevFee": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "shippingAndTaxes": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "binding": { "type": "boolean", "const": false } }, "required": [ "currency", "unitPrice", "setupPrice", "maglevFee", "shippingAndTaxes", "binding" ] }, "requestId": { "type": "string" } }, "required": [ "capability", "inputSchema", "execution", "requiredFiles", "pricing", "requestId" ] } } } }, "400": { "description": "Invalid input or missing idempotency header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid key or missing sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Endpoint or record unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "string" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "post_inspect" } }, "/interviews": { "post": { "summary": "Start a founder or manufacturer interview.", "x-scope": "interviews:write", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "founder", "manufacturer" ] } }, "required": [ "kind" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "interview": { "$ref": "#/components/schemas/Interview" }, "requestId": { "type": "string" } }, "required": [ "interview", "requestId" ] } } } }, "400": { "description": "Invalid input or missing idempotency header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid key or missing sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "string" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "post_interviews" } }, "/interviews/{id}": { "get": { "summary": "Read an interview.", "x-scope": "interviews:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "interview": { "$ref": "#/components/schemas/Interview" }, "requestId": { "type": "string" } }, "required": [ "interview", "requestId" ] } } } }, "400": { "description": "Invalid input or missing idempotency header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid key or missing sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Endpoint or record unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "string" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get_interviews_id" } }, "/interviews/{id}/messages": { "post": { "summary": "Answer the interviewer. Send the current version; 409 on conflict.", "x-scope": "interviews:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "maxLength": 4000, "minLength": 1 }, "version": { "type": "integer", "minimum": 0 } }, "required": [ "message", "version" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "interview": { "$ref": "#/components/schemas/Interview" }, "missing": { "type": "array", "items": { "type": "string" } }, "engine": { "type": "string", "enum": [ "llm", "guided" ] }, "requestId": { "type": "string" } }, "required": [ "interview", "missing", "engine", "requestId" ] } } } }, "400": { "description": "Invalid input or missing idempotency header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid key or missing sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Endpoint or record unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version, publication or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Missing facts, turn limit or quantity below MOQ", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "string" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "post_interviews_id_messages" } }, "/interviews/{id}/publish": { "post": { "summary": "Publish the extracted record. Manufacturer records become self reported capabilities pending Maglev review; founder records become briefs.", "x-scope": "interviews:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm": { "type": "boolean", "const": true }, "version": { "type": "integer", "minimum": 0 } }, "required": [ "confirm", "version" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "brief": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "process": { "anyOf": [ { "type": "string", "enum": [ "cnc", "pcba", "injection_molding", "sheet_metal", "3d_printing", "wire_harness", "assembly", "testing" ] }, { "type": "null" } ] }, "materials": { "type": "array", "items": { "type": "string" } }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minQuantity": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "unitPriceUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "setupPriceUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "leadTimeDays": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "toleranceMm": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "certifications": { "type": "array", "items": { "type": "string" } }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quantity": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "quote": { "type": "string" } }, "required": [ "field", "quote" ] } }, "status": { "const": "reviewed_brief", "type": "string" } }, "required": [ "id", "company", "process", "materials", "country", "minQuantity", "unitPriceUsd", "setupPriceUsd", "leadTimeDays", "toleranceMm", "certifications", "description", "quantity", "evidence", "status" ] }, "discoverInput": { "type": "object", "properties": { "query": { "type": "string" }, "process": { "type": "string" }, "quantity": { "type": "integer" }, "material": { "type": "string" } }, "required": [ "query", "process", "quantity", "material" ] }, "note": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "brief", "discoverInput", "note", "requestId" ] }, { "type": "object", "properties": { "capability": { "$ref": "#/components/schemas/CapabilityRecord" }, "note": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "capability", "note", "requestId" ] } ] } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "capability": { "$ref": "#/components/schemas/CapabilityRecord" }, "note": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "capability", "note", "requestId" ] } } } }, "400": { "description": "Invalid input or missing idempotency header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid key or missing sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Endpoint or record unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version, publication or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Missing facts, turn limit or quantity below MOQ", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "string" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "post_interviews_id_publish", "description": "Confirm reviewed facts at the current version. A founder returns a brief. A manufacturer returns a capability record: 201 when created, 200 when already present. Live capabilities initially remain self-reported within the organization." } }, "/capabilities": { "get": { "summary": "The catalog visible to this key.", "x-scope": "discover", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/Capability" } }, "mode": { "type": "string", "enum": [ "sandbox", "live" ] }, "requestId": { "type": "string" } }, "required": [ "capabilities", "mode", "requestId" ] } } } }, "401": { "description": "Invalid key or missing sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "string" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get_capabilities" } }, "/review-queue": { "get": { "summary": "Self reported live capabilities awaiting Maglev review (Maglev session).", "security": [ { "SessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/capabilities/{id}/review": { "post": { "summary": "Publish a reviewed capability (Maglev session).", "security": [ { "SessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "publish": { "type": "boolean" } }, "required": [ "publish" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/run": { "post": { "summary": "Save a quote request against a capability. Requires Idempotency-Key. Never places an order.", "x-scope": "runs:own", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "capabilityId": { "type": "string", "maxLength": 100 }, "input": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": 1, "maximum": 10000000 }, "specification": { "type": "string", "minLength": 10, "maxLength": 4000 } }, "required": [ "quantity", "specification" ] } }, "required": [ "capabilityId", "input" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "$ref": "#/components/schemas/Run" }, "replayed": { "type": "boolean", "const": true }, "requestId": { "type": "string" } }, "required": [ "run", "replayed", "requestId" ] } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "$ref": "#/components/schemas/Run" }, "requestId": { "type": "string" } }, "required": [ "run", "requestId" ] } } } }, "400": { "description": "Invalid input or missing idempotency header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid key or missing sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Endpoint or record unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version, publication or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Missing facts, turn limit or quantity below MOQ", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "string" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "post_run", "description": "Saves a quote request only. New requests return 201; identical idempotent replays return 200. Does not dispatch to suppliers, place orders, charge money or certify a product." } }, "/runs": { "get": { "summary": "Your saved runs.", "x-scope": "runs:own", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/Run" } }, "requestId": { "type": "string" } }, "required": [ "runs", "requestId" ] } } } }, "401": { "description": "Invalid key or missing sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "string" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get_runs" } }, "/runs/{id}": { "get": { "summary": "One run.", "x-scope": "runs:own", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "run": { "$ref": "#/components/schemas/Run" }, "requestId": { "type": "string" } }, "required": [ "run", "requestId" ] } } } }, "400": { "description": "Invalid input or missing idempotency header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid key or missing sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Endpoint or record unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "string" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get_runs_id" } }, "/factories": { "get": { "summary": "List the factories Maglev works with. Never carries contact details; at most 50 per page.", "x-scope": "network:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free text over English and Chinese names, specialty, capabilities, city and directory id", "schema": { "type": "string" } }, { "name": "process", "in": "query", "required": false, "description": "One manufacturing process, for example cnc, pcba, injection_molding", "schema": { "type": "string" } }, { "name": "city", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "startupFriendly", "in": "query", "required": false, "description": "yes", "schema": { "type": "string" } }, { "name": "answeredUs", "in": "query", "required": false, "description": "true: only factories that have answered Maglev", "schema": { "type": "string" } }, { "name": "minQuantityAtMost", "in": "query", "required": false, "description": "Only factories whose stated minimum for the process is at most this", "schema": { "type": "integer" } }, { "name": "confidence", "in": "query", "required": false, "description": "verified, reported or unverified", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "pageSize", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 50 } }, { "name": "includeQuarantined", "in": "query", "required": false, "description": "Maglev keys only", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "factories": { "type": "array", "items": { "$ref": "#/components/schemas/FactoryListItem" } }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer" }, "importedThrough": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factories/search": { "get": { "summary": "Alias of GET /factories with q.", "x-scope": "network:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factories/{id}": { "get": { "summary": "One factory by uuid or directory id. Customers receive selected manufacturing fields. Production keys with contacts:read also receive normalized business contacts; each such read is audited and capped at 300 per key per day. Raw directory, source, verification and interaction notes require a live internal maglev:* key.", "x-scope": "network:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "uuid or mfg-, int-, or eng- directory id, such as mfg-sz-robotics-001", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "factory": { "type": "object", "properties": { "contacts": { "anyOf": [ { "type": "object", "properties": { "contactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contactEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contactPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contactWechat": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "directoryFields": { "type": "object", "properties": {} } } }, { "type": "null" } ] }, "contactsNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "whatTheyToldUs": { "type": "object", "properties": { "answeredSummary": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contactedNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "communityComments": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastAnsweredAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sources": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "directoryFields": { "type": "object", "properties": {} }, "certifications": { "type": "array", "items": { "type": "object", "properties": {} } } } } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/factories/{id}/interactions": { "get": { "summary": "Raw internal mail threads and call notes for a factory. Requires a live internal maglev:* key and is audited. Customer and sandbox keys cannot read this shared correspondence, including snippets and summaries; the legacy interactions:read scope does not grant access.", "x-scope": "maglev:*", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "bodies", "in": "query", "required": false, "description": "true to include message bodies (max 20 messages)", "schema": { "type": "string" } }, { "name": "transcripts", "in": "query", "required": false, "description": "true to include call transcripts", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "threads": { "type": "array", "items": { "type": "object", "properties": { "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "firstMessageAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastMessageAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "messageCount": { "type": "integer" }, "hasReply": { "type": "boolean" }, "participants": { "type": "array", "items": { "type": "string" } }, "messages": { "type": "array", "items": { "type": "object", "properties": { "senderDomain": { "type": "string" }, "sentAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snippet": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } }, "callNotes": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "createdAtSource": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "participants": { "type": "array", "items": { "type": "string" } }, "usable": { "type": "string" }, "summaryMarkdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "transcriptText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "directoryNotes": { "type": "object", "properties": {} }, "importedThrough": { "anyOf": [ { "type": "string", "description": "Last refresh of the mail mirror" }, { "type": "null" } ] }, "coverageNote": { "type": "string" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/network/summary": { "get": { "summary": "Counts of the network visible to this key: total, by process, by region, answered us, with certifications.", "x-scope": "network:read", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer" }, "byProcess": { "type": "object", "properties": {} }, "byRegion": { "type": "object", "properties": {} }, "answeredUs": { "type": "integer" }, "withCertifications": { "type": "integer" }, "importedThrough": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/knowledge/search": { "get": { "summary": "Full text search over explicitly published document revisions. Sandbox keys see published playbooks only. Internal categories and paths do not grant access; an empty published corpus returns no hits.", "x-scope": "knowledge:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "description": "playbook, research, spec or legal", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "hits": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "title": { "type": "string" }, "kind": { "type": "string" }, "headline": { "type": "string" }, "fileModifiedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "count": { "type": "integer" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/knowledge/documents": { "get": { "summary": "One explicitly published document revision by exact repo path (production keys). Unpublished, changed and missing revisions return 404.", "x-scope": "knowledge:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "path", "in": "query", "required": true, "description": "Exact path returned by knowledge/search for a currently published revision", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "path": { "type": "string" }, "title": { "type": "string" }, "kind": { "type": "string" }, "content": { "type": "string" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lifecycle": { "get": { "summary": "The hardware lifecycle as Maglev's playbooks define it: 35 stages in six phases, each with inputs, outputs, Maglev's role, the action kinds that run it, and its availability today.", "x-scope": "lifecycle:read", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "phases": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } }, "stages": { "type": "array", "items": { "$ref": "#/components/schemas/Stage" } }, "counts": { "type": "object", "properties": { "available": { "type": "integer" }, "coordinated": { "type": "integer" }, "planned": { "type": "integer" } } } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/lifecycle/{stageId}": { "get": { "summary": "One stage, with an example request body for its action kinds.", "x-scope": "lifecycle:read", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "stageId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "stage": { "$ref": "#/components/schemas/Stage" }, "howToRequest": { "type": "object", "properties": {} } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/actions/kinds": { "get": { "summary": "Every action kind with its JSON schema for input and output, availability and stage ids. Also listed under x-action-kinds in this document.", "x-scope": "lifecycle:read", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "kinds": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "availability": { "type": "string" }, "stageIds": { "type": "array", "items": { "type": "string" } }, "cost": { "type": "string" }, "inputSchema": { "type": "object" }, "outputSchema": { "type": "object" } }, "required": [ "kind", "name", "description", "availability", "stageIds", "cost", "inputSchema", "outputSchema" ] } }, "count": { "type": "integer" }, "note": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "kinds", "count", "note", "requestId" ] } } } }, "401": { "description": "Invalid key or missing sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "string" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get_actions_kinds" } }, "/projects": { "post": { "summary": "Open a project: the thing being built and the batch it is at.", "description": "Save a project brief. Defaults to first_batch and markets US. Creation does not support idempotency keys. Strings are trimmed before validation; intake must serialize to at most 8192 characters; maximum body size is 12000 bytes.", "x-scope": "projects:write", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "product": { "anyOf": [ { "type": "string", "maxLength": 400 }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] }, "targetQuantity": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 10000000 }, { "type": "null" } ] }, "stage": { "type": "string", "enum": [ "prototype", "first_batch", "second_batch", "later" ], "default": "first_batch" }, "markets": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 }, "maxItems": 20, "default": [ "US" ] }, "intake": { "type": "object", "description": "At most 8192 serialized characters. Updates replace the whole object.", "default": {} } }, "required": [ "name" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/Project" }, "note": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "project", "note", "requestId" ] } } } }, "400": { "description": "Invalid input or missing idempotency header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid key or missing sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "string" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "post_projects" }, "get": { "summary": "Your newest 50 projects. Count is the number returned; no pagination is currently exposed.", "x-scope": "projects:write", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "count": { "type": "integer" }, "requestId": { "type": "string" } }, "required": [ "projects", "count", "requestId" ] } } } }, "401": { "description": "Invalid key or missing sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "string" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get_projects", "description": "Returns at most the newest 50 projects. Count is the number returned, not the total saved. This endpoint currently has no pagination." } }, "/projects/{id}": { "get": { "summary": "One project with action counts by status.", "x-scope": "projects:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/Project" }, "actions": { "type": "object", "properties": { "total": { "type": "integer" }, "byStatus": { "type": "object", "additionalProperties": { "type": "integer" } } }, "required": [ "total", "byStatus" ] }, "requestId": { "type": "string" } }, "required": [ "project", "actions", "requestId" ] } } } }, "400": { "description": "Invalid input or missing idempotency header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid key or missing sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Endpoint or record unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "string" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get_projects_id" }, "patch": { "summary": "Update project fields. Intake replaces the whole object; structured intent edits require expectedContextVersion.", "x-scope": "projects:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "product": { "anyOf": [ { "type": "string", "maxLength": 400 }, { "type": "null" } ] }, "category": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] }, "targetQuantity": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 10000000 }, { "type": "null" } ] }, "stage": { "type": "string", "enum": [ "prototype", "first_batch", "second_batch", "later" ] }, "markets": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 40 }, "maxItems": 20 }, "intake": { "type": "object", "description": "At most 8192 serialized characters. Updates replace the whole object." } }, "required": [], "anyOf": [ { "required": [ "name" ] }, { "required": [ "product" ] }, { "required": [ "category" ] }, { "required": [ "targetQuantity" ] }, { "required": [ "stage" ] }, { "required": [ "markets" ] }, { "required": [ "intake" ] } ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "project": { "$ref": "#/components/schemas/Project" }, "requestId": { "type": "string" } }, "required": [ "project", "requestId" ] } } } }, "400": { "description": "Invalid input or missing idempotency header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid key or missing sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Endpoint or record unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "string" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "patch_projects_id", "description": "Update at least one supported project field. Intake replaces the whole object. Strings are trimmed before validation; intake must serialize to at most 8192 characters; maximum body size is 12000 bytes. Supply expectedContextVersion from the current project. It is required for manufacturing-intent updates; changed context returns 409." } }, "/projects/{id}/actions": { "get": { "summary": "The newest 100 actions on a project, each paired with delivery summaries. No pagination is currently exposed.", "x-scope": "projects:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "actions": { "type": "array", "items": { "$ref": "#/components/schemas/ActionListEntry" } }, "count": { "type": "integer" }, "draft": { "const": true }, "requestId": { "type": "string" } }, "required": [ "actions", "count", "draft", "requestId" ] } } } }, "400": { "description": "Invalid input or missing idempotency header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid key or missing sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Endpoint or record unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "string" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get_projects_id_actions", "description": "Returns at most the newest 100 actions for a project, each as an action/deliveries entry. Count is the number returned. Delivery entries are summaries; use GET /deliveries/{id} for message bodies. No pagination is currently exposed." }, "post": { "summary": "Request an action along the lifecycle. Available kinds return drafts; coordinated kinds create work items. Delivery drafts wait for approval.", "description": "Save and run a supported action. New requests return 201; an identical replay with the original idempotency key returns 200, including running and failed records. Output is a draft; delivery drafts require approval. A lost response does not prove failure.", "x-scope": "actions:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "8 to 120 characters, unique per request; replays return the original action", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "description": "One of GET /actions/kinds", "minLength": 1, "maxLength": 80 }, "input": { "type": "object", "properties": {}, "default": {} } }, "required": [ "kind" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/Action" }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/DeliverySummary" } }, "task": { "anyOf": [ { "$ref": "#/components/schemas/TaskSummary" }, { "type": "null" } ] }, "draft": { "const": true }, "note": { "type": "string" }, "replayed": { "type": "boolean" }, "next": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "action", "deliveries", "task", "draft", "note", "replayed", "next", "requestId" ] } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/Action" }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/DeliverySummary" } }, "task": { "anyOf": [ { "$ref": "#/components/schemas/TaskSummary" }, { "type": "null" } ] }, "draft": { "const": true }, "note": { "type": "string" }, "replayed": { "type": "boolean" }, "next": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "action", "deliveries", "task", "draft", "note", "replayed", "next", "requestId" ] } } } }, "400": { "description": "Invalid input or missing idempotency header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid key or missing sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Endpoint or record unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version, publication or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "string" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Action generation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Dependency temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "post_projects_id_actions" } }, "/actions": { "get": { "summary": "Your newest 100 matching actions across projects, each paired with delivery summaries. No pagination is currently exposed.", "x-scope": "actions:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "actions": { "type": "array", "items": { "$ref": "#/components/schemas/ActionListEntry" } }, "count": { "type": "integer" }, "draft": { "const": true }, "requestId": { "type": "string" } }, "required": [ "actions", "count", "draft", "requestId" ] } } } }, "400": { "description": "Invalid input or missing idempotency header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid key or missing sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "string" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get_actions", "description": "Returns at most the newest 100 matching actions, each as an action/deliveries entry. Count is the number returned. No pagination is currently exposed." } }, "/actions/{id}": { "get": { "summary": "One action with its output.", "x-scope": "actions:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "$ref": "#/components/schemas/Action" }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/DeliverySummary" } }, "task": { "anyOf": [ { "$ref": "#/components/schemas/TaskSummary" }, { "type": "null" } ] }, "draft": { "const": true }, "requestId": { "type": "string" } }, "required": [ "action", "deliveries", "task", "draft", "requestId" ] } } } }, "400": { "description": "Invalid input or missing idempotency header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid key or missing sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Endpoint or record unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "string" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get_actions_id", "description": "Returns an action, delivery summaries and an optional coordination task summary. The kind-specific output is at action.output.result when output is present. Use GET /deliveries/{id} for message bodies." } }, "/deliveries": { "get": { "summary": "Your newest 100 matching outbound messages and their status. Count is the number returned; no pagination is currently exposed.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } }, "count": { "type": "integer" }, "draft": { "const": true }, "requestId": { "type": "string" } }, "required": [ "deliveries", "count", "draft", "requestId" ] } } } }, "400": { "description": "Invalid input or missing idempotency header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid key or missing sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "string" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "get_deliveries", "description": "Returns at most the newest 100 matching deliveries. Count is the number returned, not the total saved. No pagination is currently exposed." } }, "/deliveries/{id}": { "get": { "summary": "One delivery and its recoverable email dispatch receipt. Provider acceptance is not confirmation of recipient delivery.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery": { "$ref": "#/components/schemas/Delivery" }, "to": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "factoryId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "address", "factoryId" ] }, "cc": { "type": "array", "items": { "type": "string" } }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyEn": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyZh": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "transport": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "requestId": { "type": "string" }, "draft": { "const": true }, "dispatch": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "ready", "sending", "uncertain", "failed", "accepted" ] }, "attempts": { "type": "integer" }, "firstAttemptAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryBefore": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "leaseExpiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastOutcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "providerMessageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payloadSha256": { "type": "string" }, "providerAccepted": { "type": "boolean" }, "recipientDeliveryConfirmed": { "const": false }, "receipt": { "type": "object", "properties": { "scope": { "const": "provider_email" }, "providerDeliveryReported": { "type": "boolean" }, "events": { "type": "object", "properties": { "sent": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "delivered": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "delivery_delayed": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "bounced": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "complained": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "failed": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "suppressed": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" } } }, "note": { "type": "string", "description": "Provider events do not prove individual copy-recipient delivery, reading, a reply or production acceptance." } }, "required": [ "scope", "providerDeliveryReported", "events", "note" ] } }, "required": [ "id", "status", "attempts", "firstAttemptAt", "retryBefore", "leaseExpiresAt", "lastOutcome", "providerMessageId", "acceptedAt", "payloadSha256", "providerAccepted", "recipientDeliveryConfirmed", "receipt" ] }, { "type": "null" } ] } }, "required": [ "delivery", "to", "cc", "subject", "bodyEn", "bodyZh", "status", "transport", "requestId", "draft", "dispatch" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/deliveries/{id}/review": { "get": { "summary": "Read the exact current draft recipient, copy list, subject, bodies and project fingerprint before approval. Live key only. Resolves the current supplier contact but approves and sends nothing. Show the complete result to the principal; echo reviewSha256 as expectedReviewSha256 only after their approval. Changed content, contact or project invalidates that approval.", "x-scope": "approvals:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "review": { "type": "object", "properties": { "deliveryId": { "type": "string", "format": "uuid" }, "actionId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "projectVersion": { "type": "string" }, "channel": { "type": "string" }, "from": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "to": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "type": "string" }, "factoryId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "factoryName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "address", "factoryId", "factoryName" ] }, "cc": { "type": "array", "items": { "type": "string" } }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyEn": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyZh": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "reviewSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "effect": { "type": "string" }, "note": { "type": "string" } }, "required": [ "deliveryId", "actionId", "projectId", "projectVersion", "channel", "from", "to", "cc", "subject", "bodyEn", "bodyZh", "reviewSha256", "effect", "note" ] } }, "required": [ "review" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Draft or current recipient/context is unavailable for review", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/deliveries/{id}/approve": { "post": { "summary": "Approve the exact reviewed draft by sending expectedReviewSha256 from GET /deliveries/{id}/review after principal approval. A first approval without it returns approval_review_required (409); changed recipient, content or context returns approval_review_changed (409). Sandbox cannot send. The exact factory address, copy list, subject and bodies are frozen with a provider idempotency key before sending. Missing contact or stale RFQ context returns 409 without approval. Repeating approval returns the saved state; use retry for an unresolved dispatch. Email without configured transport remains approved and unsent. WeChat remains explicitly manual. Provider acceptance is not delivery or a supplier reply.", "x-scope": "approvals:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expectedReviewSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "expectedReviewSha256" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery": { "$ref": "#/components/schemas/Delivery" }, "to": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "factoryId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "address", "factoryId" ] }, "cc": { "type": "array", "items": { "type": "string" } }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyEn": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyZh": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "transport": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "requestId": { "type": "string" }, "dispatch": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "ready", "sending", "uncertain", "failed", "accepted" ] }, "attempts": { "type": "integer" }, "firstAttemptAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryBefore": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "leaseExpiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastOutcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "providerMessageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payloadSha256": { "type": "string" }, "providerAccepted": { "type": "boolean" }, "recipientDeliveryConfirmed": { "const": false }, "receipt": { "type": "object", "properties": { "scope": { "const": "provider_email" }, "providerDeliveryReported": { "type": "boolean" }, "events": { "type": "object", "properties": { "sent": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "delivered": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "delivery_delayed": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "bounced": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "complained": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "failed": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "suppressed": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" } } }, "note": { "type": "string", "description": "Provider events do not prove individual copy-recipient delivery, reading, a reply or production acceptance." } }, "required": [ "scope", "providerDeliveryReported", "events", "note" ] } }, "required": [ "id", "status", "attempts", "firstAttemptAt", "retryBefore", "leaseExpiresAt", "lastOutcome", "providerMessageId", "acceptedAt", "payloadSha256", "providerAccepted", "recipientDeliveryConfirmed", "receipt" ] }, { "type": "null" } ] }, "note": { "type": "string" } }, "required": [ "delivery", "to", "cc", "subject", "bodyEn", "bodyZh", "status", "transport", "requestId", "dispatch", "note" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Changed context, missing contact, unsafe retry, expired deduplication or changed provider identity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider outcome could not be persisted; read the saved delivery before recovering the same dispatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/deliveries/{id}/retry": { "post": { "summary": "Recover the same approved email dispatch. The exact payload and provider key are reused only after a 60-second worker lease and within 23 hours of the first attempt. Current caller and original approving keys, project context, payload and provider credential are rechecked. Expired deduplication or changed provider identity requires reconciliation, never blind resend. Legacy deliveries have no recoverable dispatch. Read GET /deliveries/{id} after an interrupted response.", "x-scope": "approvals:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery": { "$ref": "#/components/schemas/Delivery" }, "to": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "factoryId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "address", "factoryId" ] }, "cc": { "type": "array", "items": { "type": "string" } }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyEn": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyZh": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "transport": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "requestId": { "type": "string" }, "dispatch": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "ready", "sending", "uncertain", "failed", "accepted" ] }, "attempts": { "type": "integer" }, "firstAttemptAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retryBefore": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "leaseExpiresAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastOutcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "providerMessageId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "acceptedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "payloadSha256": { "type": "string" }, "providerAccepted": { "type": "boolean" }, "recipientDeliveryConfirmed": { "const": false }, "receipt": { "type": "object", "properties": { "scope": { "const": "provider_email" }, "providerDeliveryReported": { "type": "boolean" }, "events": { "type": "object", "properties": { "sent": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "delivered": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "delivery_delayed": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "bounced": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "complained": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "failed": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" }, "suppressed": { "type": "string", "description": "Earliest authenticated provider event timestamp for this email.", "format": "date-time" } } }, "note": { "type": "string", "description": "Provider events do not prove individual copy-recipient delivery, reading, a reply or production acceptance." } }, "required": [ "scope", "providerDeliveryReported", "events", "note" ] } }, "required": [ "id", "status", "attempts", "firstAttemptAt", "retryBefore", "leaseExpiresAt", "lastOutcome", "providerMessageId", "acceptedAt", "payloadSha256", "providerAccepted", "recipientDeliveryConfirmed", "receipt" ] }, { "type": "null" } ] }, "note": { "type": "string" } }, "required": [ "delivery", "to", "cc", "subject", "bodyEn", "bodyZh", "status", "transport", "requestId", "dispatch", "note" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Changed context, missing contact, unsafe retry, expired deduplication or changed provider identity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Provider outcome could not be persisted; read the saved delivery before recovering the same dispatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/deliveries/{id}/reject": { "post": { "summary": "Reject a draft delivery; bodies are kept for the record. Once approval has claimed the draft, dispatch may already be in flight and rejection returns 409. This endpoint cannot cancel an approved send.", "x-scope": "approvals:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 400 } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery": { "$ref": "#/components/schemas/Delivery" }, "to": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "factoryId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "name", "address", "factoryId" ] }, "cc": { "type": "array", "items": { "type": "string" } }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyEn": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyZh": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "transport": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "delivery", "to", "cc", "subject", "bodyEn", "bodyZh", "status", "transport", "note", "requestId" ] } } } }, "400": { "description": "Invalid input or missing idempotency header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid key or missing sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Endpoint or record unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version, publication or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "string" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "post_deliveries_id_reject" } }, "/outbox": { "get": { "summary": "Live manual outbox deliveries across owners (Maglev keys only). Uncertain provider dispatches and legacy resend_failed messages are excluded. Use only the frozen approved recipient.", "x-scope": "maglev:*", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "required": false, "description": "queued or needs_contact", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "requestId": { "type": "string" } } } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/deliveries/{id}/sent": { "post": { "summary": "Record a live addressed manual outbox delivery as sent (Maglev keys only). Provider dispatches and unknown outcomes are rejected; never use this endpoint to bypass provider reconciliation.", "x-scope": "maglev:*", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sentBy": { "type": "string", "minLength": 1, "maxLength": 120 }, "reference": { "type": "string", "description": "For example the Gmail message id", "maxLength": 200 } }, "required": [ "sentBy" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery": { "$ref": "#/components/schemas/Delivery" }, "to": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "factoryId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "name", "address", "factoryId" ] }, "cc": { "type": "array", "items": { "type": "string" } }, "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyEn": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bodyZh": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "transport": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "delivery", "to", "cc", "subject", "bodyEn", "bodyZh", "status", "transport", "note", "requestId" ] } } } }, "400": { "description": "Invalid input or missing idempotency header", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Invalid key or missing sign-in", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Insufficient access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Endpoint or record unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Version, publication or idempotency conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds before retrying", "schema": { "type": "string" } } } }, "500": { "description": "Server failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "operationId": "post_deliveries_id_sent" } }, "/shipping/estimate": { "post": { "summary": "Deterministic freight and landed cost estimate, China to US. Chargeable weight, cost band per mode with its published source, fuel surcharge range, transit days, the duty stack as of Sep 2026, and a landed range. Every number carries a basis; nothing is binding.", "x-scope": "shipping:read", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cartons": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "lengthCm": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 }, "widthCm": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 }, "heightCm": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 }, "weightKg": { "type": "number", "exclusiveMinimum": 0, "maximum": 2000 }, "count": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "lengthCm", "widthCm", "heightCm", "weightKg", "count" ] } }, "totals": { "type": "object", "properties": { "grossWeightKg": { "type": "number", "exclusiveMinimum": 0, "maximum": 100000 }, "volumeM3": { "type": "number", "minimum": 0, "maximum": 1000 } }, "required": [ "grossWeightKg", "volumeM3" ] }, "originCity": { "type": "string", "minLength": 2, "maxLength": 60 }, "destination": { "type": "object", "properties": { "country": { "type": "string", "const": "US" }, "postcode": { "type": "string", "maxLength": 10 }, "state": { "type": "string", "minLength": 2, "maxLength": 2 }, "city": { "type": "string", "maxLength": 60 } }, "required": [ "country" ] }, "modes": { "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "air_express", "air_freight", "ocean_lcl" ] } }, "declaredValueUsd": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100000000 }, { "type": "null" } ] }, "hts": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "productCategory": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "batteries": { "type": "string", "enum": [ "none", "contained", "packed_with", "standalone" ] }, "live": { "type": "boolean", "description": "Request optional market quotes; provider availability and additional limits apply." } }, "anyOf": [ { "required": [ "cartons" ] }, { "required": [ "totals" ] } ], "description": "Provide cartons or totals. Cartons take precedence when both are present.", "required": [ "destination" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "chargeableWeightKg": { "type": "object", "properties": { "air_express": { "type": "number" }, "air_freight": { "type": "number" }, "ocean_lcl": { "type": "number" } }, "required": [ "air_express", "air_freight", "ocean_lcl" ] }, "chargeable": { "type": "object", "properties": { "air_express": { "type": "object", "properties": { "actualKg": { "type": "number" }, "volumetricKg": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "chargeableKg": { "type": "number" }, "divisor": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "volumeM3": { "type": "number" }, "chargeableCbm": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "basis": { "type": "string" } }, "required": [ "actualKg", "volumetricKg", "chargeableKg", "divisor", "volumeM3", "chargeableCbm", "basis" ] }, "air_freight": { "type": "object", "properties": { "actualKg": { "type": "number" }, "volumetricKg": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "chargeableKg": { "type": "number" }, "divisor": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "volumeM3": { "type": "number" }, "chargeableCbm": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "basis": { "type": "string" } }, "required": [ "actualKg", "volumetricKg", "chargeableKg", "divisor", "volumeM3", "chargeableCbm", "basis" ] }, "ocean_lcl": { "type": "object", "properties": { "actualKg": { "type": "number" }, "volumetricKg": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "chargeableKg": { "type": "number" }, "divisor": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "volumeM3": { "type": "number" }, "chargeableCbm": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "basis": { "type": "string" } }, "required": [ "actualKg", "volumetricKg", "chargeableKg", "divisor", "volumeM3", "chargeableCbm", "basis" ] } }, "required": [ "air_express", "air_freight", "ocean_lcl" ] }, "options": { "type": "array", "items": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "air_express", "air_freight", "ocean_lcl" ] }, "chargeableWeightKg": { "type": "number" }, "costUsdLow": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "costUsdHigh": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "baseCostUsd": { "anyOf": [ { "type": "object", "properties": { "low": { "type": "number" }, "high": { "type": "number" } }, "required": [ "low", "high" ] }, { "type": "null" } ] }, "ratePerKgUsd": { "anyOf": [ { "type": "object", "properties": { "low": { "type": "number" }, "high": { "type": "number" } }, "required": [ "low", "high" ] }, { "type": "null" } ] }, "fuelSurchargePct": { "anyOf": [ { "type": "object", "properties": { "low": { "type": "number" }, "high": { "type": "number" } }, "required": [ "low", "high" ] }, { "type": "null" } ] }, "dangerousGoods": { "anyOf": [ { "type": "object", "properties": { "surchargeUsd": { "anyOf": [ { "type": "object", "properties": { "low": { "type": "number" }, "high": { "type": "number" } }, "required": [ "low", "high" ] }, { "type": "null" } ] }, "note": { "type": "string" } }, "required": [ "surchargeUsd", "note" ] }, { "type": "null" } ] }, "transitDays": { "anyOf": [ { "type": "object", "properties": { "low": { "type": "number" }, "high": { "type": "number" } }, "required": [ "low", "high" ] }, { "type": "null" } ] }, "basis": { "type": "array", "items": { "type": "string" } }, "binding": { "const": false } }, "required": [ "mode", "chargeableWeightKg", "costUsdLow", "costUsdHigh", "baseCostUsd", "ratePerKgUsd", "fuelSurchargePct", "dangerousGoods", "transitDays", "basis", "binding" ] } }, "dutyStack": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "ratePct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "amountUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "applies", "conditional", "unknown", "terminated", "expired", "not_applicable" ] }, "appliesTo": { "anyOf": [ { "const": "all" }, { "type": "array", "items": { "type": "string", "enum": [ "air_express", "air_freight", "ocean_lcl" ] } } ] }, "basis": { "type": "string" }, "source": { "type": "string" } }, "required": [ "name", "ratePct", "amountUsd", "status", "appliesTo", "basis", "source" ] } }, "dutyEffectiveRatePct": { "type": "object", "properties": { "known": { "type": "number" }, "layersCounted": { "type": "array", "items": { "type": "string" } }, "layersUnknown": { "type": "array", "items": { "type": "string" } } }, "required": [ "known", "layersCounted", "layersUnknown" ] }, "landedRange": { "type": "object", "properties": { "lowUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "highUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "excludes": { "type": "array", "items": { "type": "string" } } }, "required": [ "lowUsd", "highUsd", "excludes" ] }, "notes": { "type": "array", "items": { "type": "string" } }, "marketQuotes": { "anyOf": [ { "type": "object", "properties": { "attribution": { "type": "string" }, "link": { "type": "string" }, "fetchedAt": { "type": "string" }, "query": { "type": "object", "properties": { "origin": { "type": "string" }, "destination": { "type": "string" }, "quantity": { "type": "number" }, "boxWeightKg": { "type": "number" }, "boxCm": { "type": "object", "properties": { "length": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "length", "width", "height" ] }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "origin", "destination", "quantity", "boxWeightKg", "boxCm", "note" ] }, "quotes": { "type": "array", "items": { "type": "object", "properties": { "freightosMode": { "type": "string" }, "mode": { "anyOf": [ { "type": "string", "enum": [ "air_express", "air_freight", "ocean_lcl", "ocean_fcl" ] }, { "type": "null" } ] }, "priceUsdLow": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "priceUsdHigh": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "transitDays": { "type": "object", "properties": { "low": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "high": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "low", "high" ] } }, "required": [ "freightosMode", "mode", "priceUsdLow", "priceUsdHigh", "currency", "transitDays" ] } }, "binding": { "const": false } }, "required": [ "attribution", "link", "fetchedAt", "query", "quotes", "binding" ] }, { "type": "null" } ] }, "marketNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "binding": { "const": false } }, "required": [ "chargeableWeightKg", "chargeable", "options", "dutyStack", "dutyEffectiveRatePct", "landedRange", "notes", "marketQuotes", "marketNote", "binding" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/shipping/track/{carrier}/{number}": { "get": { "summary": "Track a shipment through DHL unified tracking or 17TRACK. Without a configured provider key the response is HTTP 200 with availability planned and the missing environment variable named.", "x-scope": "shipping:read", "x-availability": "planned", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "carrier", "in": "path", "required": true, "description": "dhl, 17track or auto", "schema": { "type": "string", "enum": [ "dhl", "17track", "auto" ] } }, { "name": "number", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]{6,40}$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "dhl", "17track" ] }, "trackingNumber": { "type": "string" }, "availability": { "const": "live" }, "carrier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "time": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "time", "location", "description" ] } } }, "required": [ "provider", "trackingNumber", "availability", "carrier", "status", "events" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "dhl", "17track" ] }, "trackingNumber": { "type": "string" }, "availability": { "const": "planned" }, "missing": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" } }, "required": [ "provider", "trackingNumber", "availability", "missing", "message" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "dhl", "17track" ] }, "trackingNumber": { "type": "string" }, "availability": { "const": "unavailable" }, "message": { "type": "string" } }, "required": [ "provider", "trackingNumber", "availability", "message" ] } ], "type": "object", "properties": { "tried": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "dhl", "17track" ] }, "trackingNumber": { "type": "string" }, "availability": { "const": "live" }, "carrier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "events": { "type": "array", "items": { "type": "object", "properties": { "time": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "time", "location", "description" ] } } }, "required": [ "provider", "trackingNumber", "availability", "carrier", "status", "events" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "dhl", "17track" ] }, "trackingNumber": { "type": "string" }, "availability": { "const": "planned" }, "missing": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" } }, "required": [ "provider", "trackingNumber", "availability", "missing", "message" ] }, { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "dhl", "17track" ] }, "trackingNumber": { "type": "string" }, "availability": { "const": "unavailable" }, "message": { "type": "string" } }, "required": [ "provider", "trackingNumber", "availability", "message" ] } ] } }, "note": { "type": "string" } }, "required": [ "note" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/shipping/providers": { "get": { "summary": "Which tracking and rating providers are configured on this deployment (presence only, never values).", "x-scope": "shipping:read", "security": [ { "BearerAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "rating": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string" }, "configured": { "type": "boolean" }, "env": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "type": "string" } }, "required": [ "provider", "configured", "note" ] } }, "tracking": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "dhl", "17track" ] }, "configured": { "type": "boolean" }, "env": { "type": "string" }, "freeTier": { "type": "string" }, "docs": { "type": "string" } }, "required": [ "provider", "configured", "env", "freeTier", "docs" ] } }, "note": { "type": "string" } }, "required": [ "rating", "tracking", "note" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/compliance/path": { "post": { "summary": "Return a product-specific planning table of possible certification requirements and an optional draft explanation.", "x-scope": "compliance:read", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "product": { "type": "string", "minLength": 2, "maxLength": 400 }, "markets": { "default": [ "US" ], "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 8 } }, "radios": { "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 40 } }, "moduleIsPreCertified": { "type": [ "boolean", "null" ] }, "battery": { "default": "none", "type": "string", "enum": [ "none", "liion_contained", "liion_pack", "other" ] }, "mainsPowered": { "type": "boolean" }, "laser": { "type": "boolean" }, "childrensProduct": { "type": "boolean" }, "medical": { "type": "boolean" }, "explain": { "type": "boolean", "description": "Request an optional generated explanation of the deterministic table." } }, "required": [ "product" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "requirements": { "type": "array", "items": { "type": "object", "properties": { "mark": { "type": "string" }, "market": { "type": "string" }, "applies": { "type": "string", "enum": [ "yes", "likely", "confirm" ] }, "path": { "type": "string" }, "costUsdLow": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "costUsdHigh": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "weeksLow": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "weeksHigh": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "basis": { "type": "string" }, "responsibleParty": { "type": "string" } }, "required": [ "mark", "market", "applies", "path", "costUsdLow", "costUsdHigh", "weeksLow", "weeksHigh", "basis", "responsibleParty" ] } }, "notes": { "type": "array", "items": { "type": "string" } }, "explanation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "explanationNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "draft": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "note": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "requirements", "notes", "explanation", "explanationNote", "draft", "note", "requestId" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/compliance/hts-candidates": { "post": { "summary": "Return candidate tariff headings with reasoning and sources. No final classification is selected.", "x-scope": "compliance:read", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string", "minLength": 2, "maxLength": 200 }, "description": { "type": "string", "minLength": 2, "maxLength": 2000 }, "materials": { "type": "string", "maxLength": 400 }, "function": { "type": "string", "maxLength": 400 } }, "required": [ "product", "description" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "categoriesMatched": { "type": "array", "items": { "type": "string" } }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "description": { "type": "string" }, "reasoning": { "type": "string" }, "mfnRatePct": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "section301": { "anyOf": [ {}, { "type": "null" } ] }, "sources": { "type": "array", "items": { "type": "string" } }, "confidence": { "type": "string", "const": "candidate" } }, "required": [ "code", "description", "reasoning", "mfnRatePct", "section301", "sources", "confidence" ] } }, "notes": { "type": "array", "items": { "type": "string" } }, "chosen": { "type": "null" }, "note": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "categoriesMatched", "candidates", "notes", "chosen", "note", "requestId" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{id}/engineering": { "get": { "summary": "Read an owner-authorized engineering package", "description": "Live founder key only. Requires an unexpired, unrevoked owner grant for this exact key and agent project. Rechecks current membership, API context and retained engineering. Returns approved metadata and commercial terms, not original files or supplier formulas. Grant creation and revocation are session-owner actions in the engineering portal.", "x-scope": "projects:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "binding": { "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)$" }, "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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "allowPreview": { "type": "boolean" } }, "required": [ "id", "expiresAt", "allowPreview" ], "additionalProperties": false }, "engineering": { "type": "object", "properties": { "snapshotId": { "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)$" }, "snapshotSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "evidence": { "type": "string", "const": "retained_bytes_and_founder_review" }, "semanticVerification": { "type": "boolean", "const": false }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "specification": { "type": "object", "properties": { "partId": { "type": "string", "minLength": 1, "maxLength": 200 }, "revision": { "type": "string", "minLength": 1, "maxLength": 200 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "process": { "type": "string", "minLength": 1, "maxLength": 200 }, "material": { "type": "string", "minLength": 1, "maxLength": 200 }, "finish": { "type": "string", "minLength": 1, "maxLength": 200 }, "inspection": { "type": "string", "minLength": 1, "maxLength": 200 }, "unit": { "type": "string", "enum": [ "piece", "set" ] }, "quantityBasis": { "type": "string", "const": "total_build" } }, "required": [ "partId", "revision", "sha256", "process", "material", "finish", "inspection", "unit", "quantityBasis" ], "additionalProperties": false }, "intent": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1 }, "current": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "samples", "pilot", "production", "unknown" ] }, "quantity": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 10000000 }, { "type": "null" } ] }, "unit": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] }, "configuration": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] }, "revision": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] }, "confirmation": { "type": "string", "enum": [ "unconfirmed", "caller_confirmed" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "caller", "file", "interview" ] }, "reference": { "type": "string", "minLength": 1, "maxLength": 800 }, "quote": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] } }, "required": [ "kind", "reference", "quote" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "purpose", "quantity", "unit", "configuration", "revision", "confirmation", "source" ], "additionalProperties": false }, "plannedPilot": { "anyOf": [ { "type": "object", "properties": { "quantity": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 10000000 }, { "type": "null" } ] }, "unit": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] }, "period": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "caller", "file", "interview" ] }, "reference": { "type": "string", "minLength": 1, "maxLength": 800 }, "quote": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] } }, "required": [ "kind", "reference", "quote" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "quantity", "unit", "period", "source" ], "additionalProperties": false }, { "type": "null" } ] }, "forecast": { "anyOf": [ { "type": "object", "properties": { "quantity": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 10000000 }, { "type": "null" } ] }, "unit": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] }, "period": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "caller", "file", "interview" ] }, "reference": { "type": "string", "minLength": 1, "maxLength": 800 }, "quote": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] } }, "required": [ "kind", "reference", "quote" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "quantity", "unit", "period", "source" ], "additionalProperties": false }, { "type": "null" } ] }, "requirements": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "location", "quality", "material", "inspection", "deadline", "other" ] }, "detail": { "type": "string", "minLength": 1, "maxLength": 800 }, "strength": { "type": "string", "enum": [ "hard", "preference" ] }, "confirmation": { "type": "string", "enum": [ "unconfirmed", "caller_confirmed" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "caller", "file", "interview" ] }, "reference": { "type": "string", "minLength": 1, "maxLength": 800 }, "quote": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] } }, "required": [ "kind", "reference", "quote" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "kind", "detail", "strength", "confirmation", "source" ], "additionalProperties": false } }, "priorities": { "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "quality", "price", "lead_time", "scale", "location" ] } }, "prioritySource": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "caller", "file", "interview" ] }, "reference": { "type": "string", "minLength": 1, "maxLength": 800 }, "quote": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] } }, "required": [ "kind", "reference", "quote" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "schemaVersion", "current", "plannedPilot", "forecast", "requirements", "priorities", "prioritySource" ], "additionalProperties": false }, "fileCount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "totalBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "snapshotId", "snapshotSha256", "evidence", "semanticVerification", "quantity", "specification", "intent", "fileCount", "totalBytes" ], "additionalProperties": false }, "rules": { "type": "object", "properties": { "choices": { "type": "array", "items": { "type": "object", "properties": { "ruleVersionId": { "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)$" }, "supplierName": { "type": "string" }, "ruleKey": { "type": "string" }, "version": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "commercial": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "USD", "CNY", "EUR" ] }, "incoterm": { "type": "string", "enum": [ "EXW", "FCA", "CPT", "CIP", "DAP", "DPU", "DDP", "FAS", "FOB", "CFR", "CIF" ] }, "namedPlace": { "type": "string", "minLength": 1, "maxLength": 200 }, "paymentTermsId": { "type": "string", "minLength": 1, "maxLength": 200 }, "leadTimeDays": { "type": "integer", "minimum": 1, "maximum": 3650 }, "dayBasis": { "type": "string", "enum": [ "calendar", "working" ] }, "leadTimeStartsOn": { "type": "string", "minLength": 1, "maxLength": 200 }, "scopeId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "currency", "incoterm", "namedPlace", "paymentTermsId", "leadTimeDays", "dayBasis", "leadTimeStartsOn", "scopeId" ], "additionalProperties": false }, "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|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "ruleVersionId", "supplierName", "ruleKey", "version", "commercial", "validUntil" ], "additionalProperties": false } }, "truncated": { "type": "boolean" } }, "required": [ "choices", "truncated" ], "additionalProperties": false }, "originalFilesAccessible": { "type": "boolean", "const": false }, "productionAuthorized": { "type": "boolean", "const": false }, "requestId": { "type": "string" } }, "required": [ "binding", "engineering", "rules", "originalFilesAccessible", "productionAuthorized", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Grant or engineering changed, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Original evidence unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{id}/engineering/preview": { "post": { "summary": "Calculate an evidence-bound nonbinding price preview", "description": "Requires explicit preview permission in the current owner grant. Quantity and specification come from the reviewed package. Supplier authority, capacity, originals and hard requirements are rechecked. No file disclosure, order or capacity reservation. Each successful request creates a new point-in-time receipt; retries recalculate and are not firm-offer issuance.", "x-scope": "projects:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "bindingId": { "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)$" }, "ruleVersionId": { "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)$" }, "commercial": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "USD", "CNY", "EUR" ] }, "incoterm": { "type": "string", "enum": [ "EXW", "FCA", "CPT", "CIP", "DAP", "DPU", "DDP", "FAS", "FOB", "CFR", "CIF" ] }, "namedPlace": { "type": "string", "minLength": 1, "maxLength": 200 }, "paymentTermsId": { "type": "string", "minLength": 1, "maxLength": 200 }, "leadTimeDays": { "type": "integer", "minimum": 1, "maximum": 3650 }, "dayBasis": { "type": "string", "enum": [ "calendar", "working" ] }, "leadTimeStartsOn": { "type": "string", "minLength": 1, "maxLength": 200 }, "scopeId": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "currency", "incoterm", "namedPlace", "paymentTermsId", "leadTimeDays", "dayBasis", "leadTimeStartsOn", "scopeId" ], "additionalProperties": false } }, "required": [ "bindingId", "ruleVersionId", "commercial" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "bindingId": { "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)$" }, "previewId": { "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)$" }, "evidenceOrigin": { "type": "string", "const": "server_records" }, "engineering": { "type": "object", "properties": { "snapshotId": { "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)$" }, "snapshotSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "evidence": { "type": "string", "const": "retained_bytes_and_founder_review" }, "semanticVerification": { "type": "boolean", "const": false } }, "required": [ "snapshotId", "snapshotSha256", "evidence", "semanticVerification" ], "additionalProperties": false }, "result": { "type": "object", "properties": { "binding": { "type": "boolean", "const": false }, "canPlaceOrder": { "type": "boolean", "const": false }, "capacityReserved": { "type": "boolean", "const": false }, "status": { "type": "string", "enum": [ "eligible_preview", "review_required" ] }, "reasons": { "type": "array", "items": { "type": "string" } }, "evidenceMode": { "type": "string", "enum": [ "incomplete", "synthetic", "supplied_evidence" ] }, "rule": { "type": "object", "properties": { "id": { "type": "string" }, "version": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "id", "version", "sha256" ], "additionalProperties": false }, "evaluatedAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "recheckBy": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "price": { "anyOf": [ { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "USD", "CNY", "EUR" ] }, "minorUnitScale": { "type": "number", "const": 2 }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "unit": { "type": "string", "enum": [ "piece", "set" ] }, "unitPriceMinor": { "type": "string", "pattern": "^(0|[1-9]\\d*)$" }, "partTotalMinor": { "type": "string", "pattern": "^(0|[1-9]\\d*)$" }, "charges": { "type": "object", "properties": { "setupMinor": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,14})$" }, { "type": "null" } ] }, "toolingMinor": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,14})$" }, { "type": "null" } ] }, "inspectionMinor": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,14})$" }, { "type": "null" } ] }, "packagingMinor": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,14})$" }, { "type": "null" } ] }, "shippingMinor": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,14})$" }, { "type": "null" } ] }, "taxMinor": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,14})$" }, { "type": "null" } ] }, "maglevFeeMinor": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d{0,14})$" }, { "type": "null" } ] } }, "required": [ "setupMinor", "toolingMinor", "inspectionMinor", "packagingMinor", "shippingMinor", "taxMinor", "maglevFeeMinor" ], "additionalProperties": false }, "factorySubtotalMinor": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d*)$" }, { "type": "null" } ] }, "knownTotalMinor": { "type": "string", "pattern": "^(0|[1-9]\\d*)$" }, "totalMinor": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d*)$" }, { "type": "null" } ] }, "unknownCharges": { "type": "array", "items": { "type": "string" } }, "scopeId": { "type": "string" }, "exclusions": { "type": "array", "items": { "type": "string" } } }, "required": [ "currency", "minorUnitScale", "quantity", "unit", "unitPriceMinor", "partTotalMinor", "charges", "factorySubtotalMinor", "knownTotalMinor", "totalMinor", "unknownCharges", "scopeId", "exclusions" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "binding", "canPlaceOrder", "capacityReserved", "status", "reasons", "price" ], "additionalProperties": false }, "requestId": { "type": "string" } }, "required": [ "bindingId", "previewId", "evidenceOrigin", "engineering", "result", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Grant or engineering changed, expired or revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Original evidence unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{id}/engineering/transfers": { "post": { "summary": "Propose selected engineering files", "description": "Live founder key only. Submit a stable client-generated transfer UUID and metadata for 1-10 selected technical files, at most 2 MiB each and 10 MiB total including retained project files. IDs and case-insensitive relative paths must be unique; hidden, secret, legal and correspondence paths are rejected. No bytes are uploaded here. An organization owner must approve this exact manifest and portal destination in the engineering portal. Reusing the transfer ID with the same manifest returns its receipt; different content conflicts. No supplier disclosure, BOM import or production permission.", "x-scope": "projects:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "transferId": { "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)$" }, "manifest": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1 }, "files": { "minItems": 1, "maxItems": 10, "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)$" }, "path": { "type": "string", "minLength": 1, "maxLength": 400 }, "kind": { "type": "string", "enum": [ "cad", "drawing", "gerber", "prd", "spec", "product_description" ] }, "contentType": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\w.+-]+\\/[\\w.+-]+$" }, "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 2097152 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "id", "path", "kind", "contentType", "sizeBytes", "sha256" ], "additionalProperties": false } } }, "required": [ "schemaVersion", "files" ], "additionalProperties": false } }, "required": [ "transferId", "manifest" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Existing identical proposal receipt", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "transfer": { "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)$" }, "apiProjectId": { "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)$" }, "projectId": { "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" } ] }, "manifestSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "manifest": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1 }, "files": { "minItems": 1, "maxItems": 10, "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)$" }, "path": { "type": "string", "minLength": 1, "maxLength": 400 }, "kind": { "type": "string", "enum": [ "cad", "drawing", "gerber", "prd", "spec", "product_description" ] }, "contentType": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\w.+-]+\\/[\\w.+-]+$" }, "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 2097152 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "id", "path", "kind", "contentType", "sizeBytes", "sha256" ], "additionalProperties": false } } }, "required": [ "schemaVersion", "files" ], "additionalProperties": false }, "status": { "type": "string", "enum": [ "pending_owner", "approved", "received", "expired", "revoked" ] }, "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))$" }, "received": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "fileId": { "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)$" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "sizeBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "fileId", "sha256", "sizeBytes" ], "additionalProperties": false } } }, "required": [ "id", "apiProjectId", "projectId", "manifestSha256", "manifest", "status", "expiresAt", "received" ], "additionalProperties": false }, "sharingAuthorized": { "type": "boolean", "const": false }, "productionAuthorized": { "type": "boolean", "const": false }, "reviewRequired": { "type": "boolean", "const": true }, "replayed": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "transfer", "sharingAuthorized", "productionAuthorized", "reviewRequired", "requestId" ], "additionalProperties": false } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "transfer": { "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)$" }, "apiProjectId": { "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)$" }, "projectId": { "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" } ] }, "manifestSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "manifest": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1 }, "files": { "minItems": 1, "maxItems": 10, "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)$" }, "path": { "type": "string", "minLength": 1, "maxLength": 400 }, "kind": { "type": "string", "enum": [ "cad", "drawing", "gerber", "prd", "spec", "product_description" ] }, "contentType": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\w.+-]+\\/[\\w.+-]+$" }, "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 2097152 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "id", "path", "kind", "contentType", "sizeBytes", "sha256" ], "additionalProperties": false } } }, "required": [ "schemaVersion", "files" ], "additionalProperties": false }, "status": { "type": "string", "enum": [ "pending_owner", "approved", "received", "expired", "revoked" ] }, "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))$" }, "received": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "fileId": { "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)$" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "sizeBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "fileId", "sha256", "sizeBytes" ], "additionalProperties": false } } }, "required": [ "id", "apiProjectId", "projectId", "manifestSha256", "manifest", "status", "expiresAt", "received" ], "additionalProperties": false }, "sharingAuthorized": { "type": "boolean", "const": false }, "productionAuthorized": { "type": "boolean", "const": false }, "reviewRequired": { "type": "boolean", "const": true }, "replayed": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "transfer", "sharingAuthorized", "productionAuthorized", "reviewRequired", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Transfer changed, expired, revoked, over capacity, not approved or bytes do not match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds the bounded upload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Private storage is unavailable; read the receipt before retrying the same file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{id}/engineering/transfers/{transferId}": { "get": { "summary": "Read a saved engineering transfer receipt", "description": "Only the proposing live key may read this receipt. Reports recorded uploads and authorization state, including expiry or revocation. This is historical receipt metadata, not a current integrity check or engineering approval. Original files and private storage locations are not returned.", "x-scope": "projects:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "transferId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "transfer": { "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)$" }, "apiProjectId": { "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)$" }, "projectId": { "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" } ] }, "manifestSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "manifest": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1 }, "files": { "minItems": 1, "maxItems": 10, "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)$" }, "path": { "type": "string", "minLength": 1, "maxLength": 400 }, "kind": { "type": "string", "enum": [ "cad", "drawing", "gerber", "prd", "spec", "product_description" ] }, "contentType": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\w.+-]+\\/[\\w.+-]+$" }, "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 2097152 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "id", "path", "kind", "contentType", "sizeBytes", "sha256" ], "additionalProperties": false } } }, "required": [ "schemaVersion", "files" ], "additionalProperties": false }, "status": { "type": "string", "enum": [ "pending_owner", "approved", "received", "expired", "revoked" ] }, "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))$" }, "received": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "fileId": { "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)$" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "sizeBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "fileId", "sha256", "sizeBytes" ], "additionalProperties": false } } }, "required": [ "id", "apiProjectId", "projectId", "manifestSha256", "manifest", "status", "expiresAt", "received" ], "additionalProperties": false }, "sharingAuthorized": { "type": "boolean", "const": false }, "productionAuthorized": { "type": "boolean", "const": false }, "reviewRequired": { "type": "boolean", "const": true }, "replayed": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "transfer", "sharingAuthorized", "productionAuthorized", "reviewRequired", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Transfer changed, expired, revoked, over capacity, not approved or bytes do not match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds the bounded upload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Private storage is unavailable; read the receipt before retrying the same file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/projects/{id}/engineering/transfers/{transferId}/files/{entryId}": { "post": { "summary": "Retain one authorized engineering file", "description": "Canonical padded base64 of an exact manifest entry, up to 2 MiB decoded. Requires the current key, owner authorization and unchanged API/portal request. Rechecks actual retained bytes before saving an attributed receipt. After an interrupted response, read the receipt or resend identical bytes to the same entry; a verified replay is HTTP 200. Successful partial uploads remain attached and invalidate the prior engineering review. No geometry interpretation, supplier disclosure, order or capacity reservation.", "x-scope": "projects:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "transferId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "entryId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contentBase64": { "type": "string", "minLength": 4, "maxLength": 2796204, "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$" } }, "required": [ "contentBase64" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Existing upload reverified without adding another file", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "transfer": { "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)$" }, "apiProjectId": { "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)$" }, "projectId": { "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" } ] }, "manifestSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "manifest": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1 }, "files": { "minItems": 1, "maxItems": 10, "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)$" }, "path": { "type": "string", "minLength": 1, "maxLength": 400 }, "kind": { "type": "string", "enum": [ "cad", "drawing", "gerber", "prd", "spec", "product_description" ] }, "contentType": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\w.+-]+\\/[\\w.+-]+$" }, "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 2097152 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "id", "path", "kind", "contentType", "sizeBytes", "sha256" ], "additionalProperties": false } } }, "required": [ "schemaVersion", "files" ], "additionalProperties": false }, "status": { "type": "string", "enum": [ "pending_owner", "approved", "received", "expired", "revoked" ] }, "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))$" }, "received": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "fileId": { "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)$" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "sizeBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "fileId", "sha256", "sizeBytes" ], "additionalProperties": false } } }, "required": [ "id", "apiProjectId", "projectId", "manifestSha256", "manifest", "status", "expiresAt", "received" ], "additionalProperties": false }, "sharingAuthorized": { "type": "boolean", "const": false }, "productionAuthorized": { "type": "boolean", "const": false }, "reviewRequired": { "type": "boolean", "const": true }, "replayed": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "transfer", "sharingAuthorized", "productionAuthorized", "reviewRequired", "requestId" ], "additionalProperties": false } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "transfer": { "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)$" }, "apiProjectId": { "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)$" }, "projectId": { "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" } ] }, "manifestSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "manifest": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1 }, "files": { "minItems": 1, "maxItems": 10, "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)$" }, "path": { "type": "string", "minLength": 1, "maxLength": 400 }, "kind": { "type": "string", "enum": [ "cad", "drawing", "gerber", "prd", "spec", "product_description" ] }, "contentType": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[\\w.+-]+\\/[\\w.+-]+$" }, "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 2097152 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "id", "path", "kind", "contentType", "sizeBytes", "sha256" ], "additionalProperties": false } } }, "required": [ "schemaVersion", "files" ], "additionalProperties": false }, "status": { "type": "string", "enum": [ "pending_owner", "approved", "received", "expired", "revoked" ] }, "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))$" }, "received": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "fileId": { "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)$" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "sizeBytes": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "fileId", "sha256", "sizeBytes" ], "additionalProperties": false } } }, "required": [ "id", "apiProjectId", "projectId", "manifestSha256", "manifest", "status", "expiresAt", "received" ], "additionalProperties": false }, "sharingAuthorized": { "type": "boolean", "const": false }, "productionAuthorized": { "type": "boolean", "const": false }, "reviewRequired": { "type": "boolean", "const": true }, "replayed": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "transfer", "sharingAuthorized", "productionAuthorized", "reviewRequired", "requestId" ], "additionalProperties": false } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Transfer changed, expired, revoked, over capacity, not approved or bytes do not match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "JSON body exceeds the bounded upload limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Private storage is unavailable; read the receipt before retrying the same file", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rfqs": { "get": { "summary": "The managed supplier requests linked to your organization's managed projects, newest first.", "description": "Read only, and owner scoped to the buyer organization on the production key. A supplier organization key is refused with 403 supplier_audience_forbidden, because this projection carries the Maglev fee line and the buyer side of an anonymised request. Sandbox keys carry no organization and receive 404. An RFQ appears here whether it was published through POST /actions/{id}/publication or created in the Maglev workspace; an agent that has only run quote_request, without publishing it, will see an empty list. At most 100 records; truncated says whether more exist.", "x-scope": "quotes:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "description": "Managed project uuid. A project owned by another organization simply matches nothing.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "audience": { "type": "string", "const": "buyer" }, "rfqs": { "type": "array", "items": { "$ref": "#/components/schemas/RfqSummary", "description": "With invitationCount, declinedCount, respondedCount and submittedQuoteCount added" } }, "count": { "type": "integer" }, "truncated": { "type": "boolean" }, "extractedEvidence": { "type": "object", "properties": { "included": { "type": "boolean", "const": false }, "note": { "type": "string" } }, "required": [ "included", "note" ] }, "note": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "audience", "rfqs", "count", "truncated", "extractedEvidence", "note", "requestId" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/rfqs/{id}": { "get": { "summary": "One managed supplier request with its per-factory invitations and the supplier quote versions actually linked to it.", "description": "Owner scoped: an RFQ whose managed project belongs to another organization returns 404, and a supplier organization key returns 403 before any read. Absent values stay null or unknown; a workspace-created RFQ whose currency or Incoterm is still at its column default is flagged rather than reported as declared, while an RFQ published through the API stated both explicitly and is not flagged, and a missing validUntil is validity state unknown rather than valid. A quote still in draft has not been submitted and stays supplier-private, the same rule the workspace quote board applies. Declines are returned as invitations with status declined and their reason. Model-extracted quote_record output is draft evidence on the action and is never merged in here. A request published through the API can be corrected afterwards, and a correction is a new revision on the same RFQ and the same invitations rather than a second request; rfq.requested reports the current revision, revisions lists every one that was published and to whom, and each quote says which revision it answers and whether a later one superseded it.", "x-scope": "quotes:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Managed RFQ uuid", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "audience": { "type": "string", "const": "buyer" }, "rfq": { "$ref": "#/components/schemas/RfqSummary" }, "revisions": { "type": "array", "items": { "type": "object", "properties": { "revision": { "type": "integer" }, "reviewSha256": { "type": "string" }, "publishedAt": { "type": "string", "format": "date-time" }, "factoryIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } }, "required": [ "revision", "reviewSha256", "publishedAt", "factoryIds" ] }, "description": "Every reviewed revision of this request that was published, oldest first, with the recipients each one went to. Append only: correcting a published request adds a revision on the same RFQ and the same invitations and never rewrites an earlier one, so this is the record of what was disclosed, to whom and when. Empty for an RFQ created in the Maglev workspace." }, "currentRevision": { "anyOf": [ { "type": "integer", "description": "The newest published revision, whose terms rfq.requested reports; null when this RFQ was not published through the API" }, { "type": "null" } ] }, "invitations": { "type": "array", "items": { "$ref": "#/components/schemas/RfqInvitation" } }, "counts": { "type": "object", "properties": { "invitations": { "type": "integer" }, "declined": { "type": "integer" }, "quoted": { "type": "integer" }, "accepted": { "type": "integer" }, "awaitingResponse": { "type": "integer" }, "submittedQuotes": { "type": "integer" } }, "required": [ "invitations", "declined", "quoted", "accepted", "awaitingResponse", "submittedQuotes" ] }, "extractedEvidence": { "type": "object", "properties": { "included": { "type": "boolean", "const": false }, "note": { "type": "string" } }, "required": [ "included", "note" ] }, "note": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "audience", "rfq", "revisions", "currentRevision", "invitations", "counts", "extractedEvidence", "note", "requestId" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/pending-disclosures": { "get": { "summary": "Read current and historical supplier file disclosures for your organization", "description": "Read only, and owner scoped exactly as GET /rfqs: the managed project's organization on the production key, with a supplier organization refused 403 before any read and a sandbox key 404. Sending files to a directory factory with no bound supplier account grants nothing at that moment and grants the whole package the moment a Maglev operator binds an account to that factory, which is not your action and can be weeks later. Each row here is one of those outstanding promises. state pending means it has been granted to nobody yet and will be granted in full, with no second approval, if an account is bound before expiresAt. state delivered means it has already been granted and the supplier organization can read those files now. state expired or revoked grants nothing on a later binding, and republishing the same reviewed revision does not revive it. This route reads; it delivers and revokes nothing. Source audit: this list also includes recipients already bound when the request was published. The pending state is a future handover; delivered records are the revocation handles for access already granted. Counts describe the returned bounded list; inspect truncated before assuming complete coverage. Expiry stops a pending handover but does not revoke access already delivered.", "x-scope": "quotes:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "projectId", "in": "query", "required": false, "description": "Managed project uuid. A project owned by another organization simply matches nothing.", "schema": { "type": "string", "format": "uuid" } }, { "name": "rfqId", "in": "query", "required": false, "description": "Managed RFQ uuid.", "schema": { "type": "string", "format": "uuid" } }, { "name": "state", "in": "query", "required": false, "description": "One of pending, delivered, expired, revoked.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "audience": { "type": "string", "const": "buyer" }, "disclosures": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "uuid", "format": "uuid" }, "rfqId": { "type": "string", "description": "uuid", "format": "uuid" }, "projectId": { "type": "string", "description": "uuid", "format": "uuid" }, "factoryId": { "type": "string", "description": "uuid", "format": "uuid" }, "factoryNameEn": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "factoryNameZh": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fileIds": { "type": "array", "items": { "type": "string", "description": "uuid", "format": "uuid" }, "description": "The reviewed files this disclosure covers" }, "fileCount": { "type": "integer" }, "state": { "type": "string", "enum": [ "pending", "delivered", "expired", "revoked" ] }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "description": "When the promise lapses. A supplier account bound after this instant is granted nothing", "format": "date-time" }, "deliveredAt": { "anyOf": [ { "type": "string", "description": "When a supplier account was bound and the package was actually granted", "format": "date-time" }, { "type": "null" } ] }, "deliveredFileIds": { "type": "array", "items": { "type": "string", "description": "uuid", "format": "uuid" }, "description": "What binding actually granted, which is the current disclosure record that the publication receipt's grantedFileIds is not" }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedBy": { "anyOf": [ { "type": "string", "description": "uuid", "format": "uuid" }, { "type": "null" } ] }, "revokedReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revokedGrantFileIds": { "type": "array", "items": { "type": "string", "description": "uuid", "format": "uuid" }, "description": "Grants that already existed when this was revoked and were deleted. Deleting them stops further reads; it cannot unsend a file that was already downloaded" } }, "required": [ "id", "rfqId", "projectId", "factoryId", "factoryNameEn", "factoryNameZh", "fileIds", "fileCount", "state", "createdAt", "expiresAt", "deliveredAt", "deliveredFileIds", "revokedAt", "revokedBy", "revokedReason", "revokedGrantFileIds" ] } }, "counts": { "type": "object", "properties": { "pending": { "type": "integer" }, "delivered": { "type": "integer" }, "expired": { "type": "integer" }, "revoked": { "type": "integer" } }, "required": [ "pending", "delivered", "expired", "revoked" ] }, "windowDays": { "type": "integer", "description": "How long a new pending disclosure stays deliverable" }, "truncated": { "type": "boolean" }, "note": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "audience", "disclosures", "counts", "windowDays", "truncated", "note", "requestId" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/pending-disclosures/{id}/revoke": { "post": { "summary": "Take one outstanding engineering package back, and delete any grant it already caused.", "description": "What the GET's note tells you to do. Owner scoped exactly as GET /pending-disclosures, and it additionally needs the person: revocation is recorded against a named user on the row and in the audit log, an API key names an organization and not a person, so this call requires the production key AND a Maglev browser session in the same organization. A key alone answers 401 sign_in_required and a session in another organization answers 403; neither is a way to revoke on someone else's behalf. A disclosure belonging to another organization answers 404 with the same sentence as one that does not exist, so a guessed id tells you nothing. The body is JSON and its only field is an optional reason, which is copied onto the row and into the audit entry; unknown fields are rejected rather than dropped, because a misspelled one would read afterwards as a founder who gave no reason. Revoking is idempotent: a second call returns 200 with alreadyRevoked true, the first revocation's timestamp, and no second audit entry. File access is granted per supplier organization rather than per directory factory, so this reaches every other live disclosure of this same request to that organization; those are listed in cascaded and receive nothing from a later revision either. It is honest about its limits and the response says so in full: revokedGrants is what was actually deleted, retainedGrants is what was deliberately left alone because a disclosure outside this request still authorizes that organization to read that file and must be revoked separately, and openedBefore lists the reads Maglev recorded for these files by that organization before the grants went away. That last one is a floor on what was seen and never a proof that nothing was: revoking stops future reads and cannot retrieve or erase a copy that has already left Maglev.", "x-scope": "quotes:write", "security": [ { "BearerAuth": [], "SessionCookie": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Pending disclosure uuid, as returned by GET /pending-disclosures or as pendingDisclosureId on a publication receipt", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Optional reason, trimmed before validation and recorded with the revocation." } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "audience": { "type": "string", "const": "buyer" }, "disclosure": { "type": "object", "properties": { "id": { "type": "string", "description": "uuid", "format": "uuid" }, "rfqId": { "type": "string", "description": "uuid", "format": "uuid" }, "projectId": { "type": "string", "description": "uuid", "format": "uuid" }, "factoryId": { "type": "string", "description": "uuid", "format": "uuid" }, "factoryNameEn": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "factoryNameZh": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fileIds": { "type": "array", "items": { "type": "string", "description": "uuid", "format": "uuid" } }, "fileCount": { "type": "integer" }, "state": { "type": "string", "enum": [ "pending", "delivered", "expired", "revoked" ] }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "deliveredFileIds": { "type": "array", "items": { "type": "string", "description": "uuid", "format": "uuid" } }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedBy": { "anyOf": [ { "type": "string", "description": "uuid", "format": "uuid" }, { "type": "null" } ] }, "revokedReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "revokedGrantFileIds": { "type": "array", "items": { "type": "string", "description": "uuid", "format": "uuid" } } }, "required": [ "id", "rfqId", "projectId", "factoryId", "factoryNameEn", "factoryNameZh", "fileIds", "fileCount", "state", "createdAt", "expiresAt", "deliveredAt", "deliveredFileIds", "revokedAt", "revokedBy", "revokedReason", "revokedGrantFileIds" ] }, "revokedGrants": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string", "description": "uuid", "format": "uuid" }, "organisationId": { "type": "string", "description": "uuid", "format": "uuid" } }, "required": [ "fileId", "organisationId" ] }, "description": "The file grants this call deleted. Empty when the package had not been delivered yet, which is the whole point of revoking early" }, "cascaded": { "type": "array", "items": { "type": "object", "properties": { "disclosureId": { "type": "string", "description": "uuid", "format": "uuid" }, "factoryId": { "type": "string", "description": "uuid", "format": "uuid" }, "fileIds": { "type": "array", "items": { "type": "string", "description": "uuid", "format": "uuid" } } }, "required": [ "disclosureId", "factoryId", "fileIds" ] }, "description": "Other live disclosures of this same request to the same supplier organization, revoked with this one because access is per organization" }, "retainedGrants": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string", "description": "uuid", "format": "uuid" }, "organisationId": { "type": "string", "description": "uuid", "format": "uuid" }, "authorisedByDisclosureId": { "type": "string", "description": "uuid", "format": "uuid" }, "authorisedByRfqId": { "type": "string", "description": "uuid", "format": "uuid" }, "authorisedByFactoryId": { "type": "string", "description": "uuid", "format": "uuid" } }, "required": [ "fileId", "organisationId", "authorisedByDisclosureId", "authorisedByRfqId", "authorisedByFactoryId" ] }, "description": "Grants that were NOT deleted, each named with the live disclosure outside this request that still authorizes it. Revoke those to take the file back" }, "alreadyRevoked": { "type": "boolean", "description": "True when this disclosure was already revoked. The call is idempotent: the first revocation stands, nothing is deleted twice and no second audit entry is written" }, "openedBefore": { "type": "array", "items": { "type": "object", "properties": { "fileId": { "type": "string", "description": "uuid", "format": "uuid" }, "at": { "type": "string", "format": "date-time" }, "actorUserId": { "anyOf": [ { "type": "string", "description": "uuid", "format": "uuid" }, { "type": "null" } ] } }, "required": [ "fileId", "at", "actorUserId" ] }, "description": "Reads Maglev recorded for these files by that organization before the grants were deleted. It records opens through the Maglev file route only, so it is a floor on what was seen, never a proof that nothing was" }, "note": { "type": "string", "description": "What revocation is and is not, in full" }, "requestId": { "type": "string" } }, "required": [ "audience", "disclosure", "revokedGrants", "cascaded", "retainedGrants", "alreadyRevoked", "openedBefore", "note", "requestId" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Scope or mode does not allow this", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/actions/{id}/publication/review": { "get": { "summary": "Read the exact scope that publication would disclose, and the digest over it", "description": "Live founder key only, and only a key that already holds the engineering access grant for this action's API project: this returns the exact file hashes, supplier shortlist and wording that publication would disclose. It is the only way to obtain the expectedReviewSha256 that POST /actions/{id}/publication requires. Reads only: no RFQ, invitation, thread, file grant, publication row or audit entry is created, nothing is locked and nothing is authorized. The engineering snapshot and its hash come from this key's own access grant, the file list is the whole reviewed package, the part mapping is resolved from the reviewed specification, and the wording, quote-by date and anonymity are the retained draft's own; only the commercial basis and the factory selection are the caller's. Return `selection` unchanged as the publication body's `selection`, and `reviewSha256` as its `expectedReviewSha256`, after the approving owner has seen the complete review. If the source, engineering package or selected scope moves first, the digest moves with it and publication returns review_changed (409) rather than publishing stale scope.", "x-scope": "approvals:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The live quote_request action to review", "schema": { "type": "string", "format": "uuid" } }, { "name": "currency", "in": "query", "required": true, "description": "USD or CNY. Publication never defaults a commercial term, so it must be stated here.", "schema": { "type": "string", "enum": [ "USD", "CNY" ] } }, { "name": "namedPlace", "in": "query", "required": true, "description": "The named place for the Incoterm, as the supplier will be shown it", "schema": { "type": "string", "maxLength": 200 } }, { "name": "incoterm", "in": "query", "required": false, "description": "Only when the retained draft states no trade term. A term that contradicts the draft is refused, not ignored.", "schema": { "type": "string", "enum": [ "EXW", "FCA", "CPT", "CIP", "DAP", "DPU", "DDP", "FAS", "FOB", "CFR", "CIF" ] } }, { "name": "deliverTo", "in": "query", "required": false, "description": "Optional delivery destination. Omitted stays unknown rather than guessed.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "factoryIds", "in": "query", "required": false, "description": "Comma separated, at most five, each already on the draft's shortlist. Defaults to the whole shortlist when it holds five or fewer.", "schema": { "type": "string" } }, { "name": "lineId", "in": "query", "required": false, "description": "Optional BOM line override. By default the single line matching the reviewed specification is resolved on the server.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "review": { "type": "object", "properties": { "actionId": { "type": "string", "format": "uuid" }, "apiProjectId": { "type": "string", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "snapshotId": { "type": "string", "format": "uuid" }, "snapshotSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "state": { "type": "string", "enum": [ "review_required", "not_publishable" ] }, "reviewSha256": { "type": "string", "description": "Echo as expectedReviewSha256 on POST /actions/{id}/publication", "pattern": "^[a-f0-9]{64}$" }, "manifest": { "type": "object", "properties": {} }, "selection": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projectId": { "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)$" }, "snapshotId": { "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)$" }, "expectedSnapshotSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "factoryIds": { "minItems": 1, "maxItems": 5, "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)$" } }, "fileIds": { "minItems": 1, "maxItems": 11, "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)$" } }, "partMapping": { "type": "object", "properties": { "partIndex": { "type": "number", "const": 0 }, "lineId": { "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)$" }, "quantityPerUnit": { "type": "number", "const": 1 } }, "required": [ "partIndex", "lineId", "quantityPerUnit" ], "additionalProperties": false }, "currency": { "type": "string", "enum": [ "USD", "CNY" ] }, "incoterm": { "type": "string", "enum": [ "EXW", "FCA", "CPT", "CIP", "DAP", "DPU", "DDP", "FAS", "FOB", "CFR", "CIF" ] }, "namedPlace": { "type": "string", "minLength": 1, "maxLength": 200 }, "quoteBy": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "null" } ] }, "deliverTo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "anonymised": { "type": "boolean" }, "wording": { "type": "object", "properties": { "subjectZh": { "type": "string", "minLength": 1, "maxLength": 20000 }, "en": { "type": "string", "minLength": 1, "maxLength": 20000 }, "zh": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "subjectZh", "en", "zh" ], "additionalProperties": false } }, "required": [ "projectId", "snapshotId", "expectedSnapshotSha256", "factoryIds", "fileIds", "partMapping", "currency", "incoterm", "namedPlace", "quoteBy", "deliverTo", "anonymised", "wording" ], "additionalProperties": false }, "factories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organisationId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "directoryId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nameEn": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nameZh": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accountState": { "type": "string", "enum": [ "bound", "awaiting_account" ] } }, "required": [ "id", "organisationId", "directoryId", "nameEn", "nameZh", "accountState" ] } }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "filename": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "sizeBytes": { "type": "integer" } }, "required": [ "id", "kind", "filename", "sha256", "sizeBytes" ] } }, "commercial": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "USD", "CNY" ] }, "incoterm": { "type": "string" }, "namedPlace": { "type": "string" }, "quoteBy": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "deliverTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "currency", "incoterm", "namedPlace", "quoteBy", "deliverTo" ] }, "anonymised": { "type": "boolean" }, "wording": { "type": "object", "properties": { "subjectZh": { "type": "string" }, "en": { "type": "string" }, "zh": { "type": "string" } }, "required": [ "subjectZh", "en", "zh" ] }, "publicationAuthorized": { "type": "boolean" }, "productionAuthorized": { "type": "boolean" }, "eligibility": { "type": "object", "properties": { "publishable": { "type": "boolean", "description": "False when no NDA is in force between this customer organisation and Maglev, or this managed project has not recorded every release check publication requires. The reviewed scope is still returned and still hashed; publishing it would be refused with 409 nda_required or 409 publication_precondition." }, "blockers": { "type": "array", "items": { "type": "string", "enum": [ "nda", "export_attestation", "maglev_screening" ] }, "description": "The records that are missing, empty when this customer and project may disclose" }, "note": { "type": "string" } }, "required": [ "publishable", "blockers", "note" ] }, "effect": { "type": "string" }, "note": { "type": "string" } }, "required": [ "actionId", "apiProjectId", "projectId", "snapshotId", "snapshotSha256", "state", "reviewSha256", "manifest", "selection", "factories", "files", "commercial", "anonymised", "wording", "publicationAuthorized", "productionAuthorized", "eligibility", "effect", "note" ] } }, "required": [ "review" ] } } } }, "400": { "description": "The derived selection could not be bound to the reviewed source and engineering", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key, mode or engineering access grant does not authorize reading this scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such live action for this organization, or this key holds no engineering access grant on its API project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Source, engineering package or retained draft changed and the review cannot be built", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Retained engineering evidence is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/actions/{id}/publication/approval": { "post": { "summary": "Ask the founder to approve disclosing this exact reviewed revision", "description": "Live founder key only, holding the same engineering access grant publication needs. Records a durable pending approval for one reviewed revision and returns it. It publishes nothing, creates no RFQ, invitation, thread or file grant, sends no message, and above all approves nothing: the record is created with no approver, and only the founder, signed in to the Maglev workspace, can approve it. An API key cannot approve its own proposal and there is no field anywhere in this API that lets it try. The recipients, files and terms stored on the record are recomputed on the server from the same rows publication would read, so the founder is shown the disclosure that would actually be made rather than a summary the caller supplied. Re-proposing the same approvalId for the same revision returns the existing record with 200 and does not ask the founder twice; a second proposal for a revision that already has a live approval returns that one instead. An approval is single use: it authorizes exactly one publication of exactly one revision, and a change to any recipient, any file or any commercial term invalidates it rather than carrying over.", "x-scope": "approvals:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The live quote_request action whose reviewed revision is being proposed", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "approvalId": { "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)$" }, "expectedReviewSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "selection": { "type": "object", "properties": { "projectId": { "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)$" }, "snapshotId": { "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)$" }, "expectedSnapshotSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "factoryIds": { "minItems": 1, "maxItems": 5, "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)$" } }, "fileIds": { "minItems": 1, "maxItems": 11, "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)$" } }, "partMapping": { "type": "object", "properties": { "partIndex": { "type": "number", "const": 0 }, "lineId": { "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)$" }, "quantityPerUnit": { "type": "number", "const": 1 } }, "required": [ "partIndex", "lineId", "quantityPerUnit" ], "additionalProperties": false }, "currency": { "type": "string", "enum": [ "USD", "CNY" ] }, "incoterm": { "type": "string", "enum": [ "EXW", "FCA", "CPT", "CIP", "DAP", "DPU", "DDP", "FAS", "FOB", "CFR", "CIF" ] }, "namedPlace": { "type": "string", "minLength": 1, "maxLength": 200 }, "quoteBy": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "null" } ] }, "deliverTo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "anonymised": { "type": "boolean" }, "wording": { "type": "object", "properties": { "subjectZh": { "type": "string", "minLength": 1, "maxLength": 20000 }, "en": { "type": "string", "minLength": 1, "maxLength": 20000 }, "zh": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "subjectZh", "en", "zh" ], "additionalProperties": false } }, "required": [ "projectId", "snapshotId", "expectedSnapshotSha256", "factoryIds", "fileIds", "partMapping", "currency", "incoterm", "namedPlace", "quoteBy", "deliverTo", "anonymised", "wording" ], "additionalProperties": false } }, "required": [ "approvalId", "expectedReviewSha256", "selection" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "This revision already has a pending or decided approval; nothing was written", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval": { "type": "object", "properties": { "approvalId": { "type": "string", "description": "The stored approval, named as `approval.approvalId` on POST /actions/{id}/publication", "format": "uuid" }, "actionId": { "type": "string", "format": "uuid" }, "apiProjectId": { "type": "string", "format": "uuid" }, "apiKeyId": { "type": "string", "description": "The key that proposed it, and the only key that may publish under it", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "snapshotId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending_owner", "approved", "expired", "revoked", "published" ] }, "reviewSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "bindingSha256": { "type": "string", "description": "Digest over the recipients, files and terms this approval binds", "pattern": "^[a-f0-9]{64}$" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "factoryId": { "type": "string", "format": "uuid" }, "organisationId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "accountState": { "type": "string", "enum": [ "bound", "awaiting_account" ] } }, "required": [ "factoryId", "organisationId", "accountState" ] }, "description": "Exactly the factories this approval permits disclosing to" }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "sizeBytes": { "type": "integer" } }, "required": [ "id", "kind", "sha256", "sizeBytes" ] }, "description": "Exactly the files, at exactly these hashes. A file whose bytes moved is not one of these." }, "terms": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "USD", "CNY" ] }, "incoterm": { "type": "string" }, "namedPlace": { "type": "string" }, "deliverTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quoteBy": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "quantities": { "type": "array", "items": { "type": "integer" } }, "anonymised": { "type": "boolean" } }, "required": [ "currency", "incoterm", "namedPlace", "deliverTo", "quoteBy", "quantities", "anonymised" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "approvedBy": { "anyOf": [ { "type": "string", "description": "The founder who approved, null until they do", "format": "uuid" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokeReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "consumedAt": { "anyOf": [ { "type": "string", "description": "When this approval was spent. It authorizes one publication and no more.", "format": "date-time" }, { "type": "null" } ] }, "consumedRfqId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "proposedAt": { "type": "string", "format": "date-time" }, "effect": { "type": "string" } }, "required": [ "approvalId", "actionId", "apiProjectId", "apiKeyId", "projectId", "snapshotId", "status", "reviewSha256", "bindingSha256", "recipients", "files", "terms", "expiresAt", "approvedBy", "approvedAt", "revokedAt", "revokeReason", "consumedAt", "consumedRfqId", "proposedAt", "effect" ] }, "replayed": { "type": "boolean" } }, "required": [ "approval", "replayed" ] } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "approval": { "type": "object", "properties": { "approvalId": { "type": "string", "description": "The stored approval, named as `approval.approvalId` on POST /actions/{id}/publication", "format": "uuid" }, "actionId": { "type": "string", "format": "uuid" }, "apiProjectId": { "type": "string", "format": "uuid" }, "apiKeyId": { "type": "string", "description": "The key that proposed it, and the only key that may publish under it", "format": "uuid" }, "projectId": { "type": "string", "format": "uuid" }, "snapshotId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending_owner", "approved", "expired", "revoked", "published" ] }, "reviewSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "bindingSha256": { "type": "string", "description": "Digest over the recipients, files and terms this approval binds", "pattern": "^[a-f0-9]{64}$" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "factoryId": { "type": "string", "format": "uuid" }, "organisationId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "accountState": { "type": "string", "enum": [ "bound", "awaiting_account" ] } }, "required": [ "factoryId", "organisationId", "accountState" ] }, "description": "Exactly the factories this approval permits disclosing to" }, "files": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "sizeBytes": { "type": "integer" } }, "required": [ "id", "kind", "sha256", "sizeBytes" ] }, "description": "Exactly the files, at exactly these hashes. A file whose bytes moved is not one of these." }, "terms": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "USD", "CNY" ] }, "incoterm": { "type": "string" }, "namedPlace": { "type": "string" }, "deliverTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quoteBy": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "quantities": { "type": "array", "items": { "type": "integer" } }, "anonymised": { "type": "boolean" } }, "required": [ "currency", "incoterm", "namedPlace", "deliverTo", "quoteBy", "quantities", "anonymised" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "approvedBy": { "anyOf": [ { "type": "string", "description": "The founder who approved, null until they do", "format": "uuid" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokeReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "consumedAt": { "anyOf": [ { "type": "string", "description": "When this approval was spent. It authorizes one publication and no more.", "format": "date-time" }, { "type": "null" } ] }, "consumedRfqId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "proposedAt": { "type": "string", "format": "date-time" }, "effect": { "type": "string" } }, "required": [ "approvalId", "actionId", "apiProjectId", "apiKeyId", "projectId", "snapshotId", "status", "reviewSha256", "bindingSha256", "recipients", "files", "terms", "expiresAt", "approvedBy", "approvedAt", "revokedAt", "revokeReason", "consumedAt", "consumedRfqId", "proposedAt", "effect" ] }, "replayed": { "type": "boolean", "description": "True when this proposal already existed and nothing was written" } }, "required": [ "approval", "replayed" ] } } } }, "400": { "description": "The selection could not be bound to the reviewed source and engineering", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key, mode or engineering access grant does not authorize proposing this disclosure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such live action for this organization, or this key holds no engineering access grant on its API project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The reviewed scope moved, or this approvalId already names a different revision", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Retained engineering evidence is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/actions/{id}/publication": { "post": { "summary": "Publish a reviewed quote request to the selected suppliers", "description": "Live founder key only, and only under a stored founder approval. The order is: read GET /actions/{id}/publication/review, which returns the reviewed scope, the `selection` to send back unchanged and the `expectedReviewSha256` this call requires; POST /actions/{id}/publication/approval to record that revision for approval; wait for the founder to approve it in the Maglev workspace; then call this with `approval: { approvalId }`. A key on its own cannot publish, whether or not anyone happens to be signed in. The approval binds the exact recipients, the exact files and their hashes, and the exact commercial terms, so adding a factory, changing a file or changing the currency is refused with 403 publication_not_approved rather than published under the approval that was given for something else, and one approval authorizes exactly one publication. Publishes one reviewed quote_request into one explicitly selected managed project as a managed RFQ with a thread, an invitation and exactly the reviewed file grants per selected factory. Currency and Incoterm must be stated explicitly in the selection; the managed RFQ's USD and EXW column defaults are never applied to a request whose buyer did not state them. Every authority and selection is rechecked inside one transaction under the human sender's lock order and committed with the durable source mapping and audit entry, or rolled back whole. Publication itself discloses the request to the supplier, so an approved email digest does not authorize it: this returns a publication receipt and dispatches no email. An identical reviewed revision returns that revision's existing publication and writes nothing, so a revoked file grant is never restored by a retry. A different reviewed revision is published as the next revision of the same request: it reuses the RFQ, and every recipient already invited keeps its invitation and its thread and is told in that thread, while earlier revisions' rows are never rewritten. A revision is a fresh disclosure and needs its own founder approval, because the approval binds the reviewed revision it was given for and is spent by the publication it authorized; publishing revision 2 under revision 1's approval is refused with 403 publication_not_approved. A revision may add a recipient and may not drop one: dropping is refused with 409 publication_revision_recipient_removed, because withdrawing a disclosure already made is a revocation. A directory factory with no bound supplier account is published awaiting account setup, with no account created and no outreach, and its grantedFileIds is empty. That empty list does not mean the factory stays outside the disclosure: when a supplier account is later bound to that directory factory it is granted the files this founder approved for it, with no further founder approval and no second review. grantedFileIds records the grants at publication time and is not updated by that backfill, so read it as publication-time state rather than as current disclosure, and read filesOnAccountBinding as what binding will grant. That promise is bounded and withdrawable: it lapses at filesOnAccountBindingExpireAt, after which binding grants nothing, and the owner organisation can withdraw it earlier by revoking pendingDisclosureId, which also deletes any grant already issued. Revocation stops further reads and cannot unsend a file that was already downloaded. A revision re-approves the outstanding promise: it moves the pending disclosure to the corrected file set and to a fresh deadline, and a disclosure the owner has already revoked stays revoked and is not resurrected by it. GET /pending-disclosures lists what is outstanding. No order and no payment is authorized.", "x-scope": "approvals:write", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The live quote_request action to publish", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "expectedReviewSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "approval": { "type": "object", "properties": { "approvalId": { "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": [ "approvalId" ], "additionalProperties": false }, "selection": { "type": "object", "properties": { "projectId": { "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)$" }, "snapshotId": { "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)$" }, "expectedSnapshotSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "factoryIds": { "minItems": 1, "maxItems": 5, "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)$" } }, "fileIds": { "minItems": 1, "maxItems": 11, "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)$" } }, "partMapping": { "type": "object", "properties": { "partIndex": { "type": "number", "const": 0 }, "lineId": { "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)$" }, "quantityPerUnit": { "type": "number", "const": 1 } }, "required": [ "partIndex", "lineId", "quantityPerUnit" ], "additionalProperties": false }, "currency": { "type": "string", "enum": [ "USD", "CNY" ] }, "incoterm": { "type": "string", "enum": [ "EXW", "FCA", "CPT", "CIP", "DAP", "DPU", "DDP", "FAS", "FOB", "CFR", "CIF" ] }, "namedPlace": { "type": "string", "minLength": 1, "maxLength": 200 }, "quoteBy": { "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "null" } ] }, "deliverTo": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "anonymised": { "type": "boolean" }, "wording": { "type": "object", "properties": { "subjectZh": { "type": "string", "minLength": 1, "maxLength": 20000 }, "en": { "type": "string", "minLength": 1, "maxLength": 20000 }, "zh": { "type": "string", "minLength": 1, "maxLength": 20000 } }, "required": [ "subjectZh", "en", "zh" ], "additionalProperties": false } }, "required": [ "projectId", "snapshotId", "expectedSnapshotSha256", "factoryIds", "fileIds", "partMapping", "currency", "incoterm", "namedPlace", "quoteBy", "deliverTo", "anonymised", "wording" ], "additionalProperties": false } }, "required": [ "expectedReviewSha256", "approval", "selection" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "An identical reviewed revision was already published; nothing was written", "content": { "application/json": { "schema": { "type": "object", "properties": { "publication": { "type": "object", "properties": { "actionId": { "type": "string", "description": "uuid" }, "apiProjectId": { "type": "string", "description": "uuid" }, "projectId": { "type": "string", "description": "uuid", "format": "uuid" }, "rfqId": { "type": "string", "description": "uuid", "format": "uuid" }, "reviewSha256": { "type": "string", "description": "The reviewed publication revision this request was published under" }, "revision": { "type": "integer", "description": "Which reviewed revision of this request this receipt is for, counting from 1. A correction published after the request is already out is the next revision: it reuses the same RFQ and every existing recipient's invitation and thread, and appends a row per recipient rather than rewriting the earlier revision." }, "supersedes": { "anyOf": [ { "type": "object", "properties": { "revision": { "type": "integer" }, "reviewSha256": { "type": "string" }, "publishedAt": { "type": "string", "format": "date-time" } }, "required": [ "revision", "reviewSha256", "publishedAt" ], "description": "The revision this one supersedes, or null on a first publication. A pointer, never a rewrite: the superseded revision keeps its own recipients, files, terms and publication-time grants." }, { "type": "null" } ] }, "revisionNote": { "type": "string", "description": "What this revision did to the supplier side, in words." }, "apiContextSha256": { "type": "string" }, "retainedActionSha256": { "type": "string" }, "snapshotId": { "type": "string", "description": "uuid", "format": "uuid" }, "snapshotSha256": { "type": "string" }, "anonymised": { "type": "boolean" }, "commercial": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "USD", "CNY" ] }, "incoterm": { "type": "string" }, "namedPlace": { "type": "string" }, "quoteBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "deliverTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "currency", "incoterm", "namedPlace", "quoteBy", "deliverTo" ] }, "fileIds": { "type": "array", "items": { "type": "string", "description": "uuid", "format": "uuid" }, "description": "Exactly the reviewed files. Granted at publication to each factory with a bound supplier account, and granted to an awaiting-account factory when a supplier account is later bound to it" }, "factories": { "type": "array", "items": { "type": "object", "properties": { "factoryId": { "type": "string", "description": "uuid", "format": "uuid" }, "invitationId": { "type": "string", "description": "uuid", "format": "uuid" }, "threadId": { "type": "string", "description": "uuid", "format": "uuid" }, "supplierOrgId": { "anyOf": [ { "type": "string", "description": "uuid", "format": "uuid" }, { "type": "null" } ] }, "accountState": { "type": "string", "enum": [ "bound", "awaiting_account" ] }, "newRecipient": { "type": "boolean", "description": "True when this revision is the first one this factory was a recipient of, which is every factory on a first publication. False means the invitation and thread are the ones it already had, so its thread history and any quote it already submitted are still attached to them, and it was told in that thread that the terms moved." }, "grantedFileIds": { "type": "array", "items": { "type": "string", "description": "uuid", "format": "uuid" }, "description": "The file grants this publication issued. Empty for a factory awaiting account setup, and also empty for a bound factory whose disclosure the owner has revoked, because a revision grants a revoked recipient nothing. It is not updated afterwards: binding a supplier account to a directory factory grants it the whole reviewed package without changing this list, so it is a record of publication-time state rather than an audit trail of current disclosure. Read pendingDisclosureState for that" }, "filesOnAccountBinding": { "type": "array", "items": { "type": "string", "description": "uuid", "format": "uuid" }, "description": "Present only when this factory is awaiting account setup AND its pending disclosure is still live: the reviewed files it will be granted when a supplier account is bound to it, with no further founder approval and no second review. These are not grants that exist yet. Absent once pendingDisclosureState is revoked, expired or delivered, because binding would then grant nothing" }, "filesOnAccountBindingExpireAt": { "anyOf": [ { "type": "string", "description": "Present alongside filesOnAccountBinding: the instant this pending disclosure lapses. Binding a supplier account after it grants nothing. Publishing a later revision of this request does re-arm it, because a revision carries a fresh owner approval naming this recipient; revoke pendingDisclosureId to stop that", "format": "date-time" }, { "type": "null" } ] }, "pendingDisclosureId": { "anyOf": [ { "type": "string", "description": "On EVERY recipient, whether or not it had a supplier account at publication time: the disclosure to read on GET /pending-disclosures, and the one the owner organisation revokes to take this package back from this factory. A recipient that was already bound has one too, recorded as delivered, because revoking it is the only way to delete the grants it already holds. Null only for a recipient this publication disclosed no files to", "format": "uuid" }, { "type": "null" } ] }, "pendingDisclosureState": { "anyOf": [ { "type": "string", "enum": [ "pending", "delivered", "expired", "revoked" ], "description": "On every recipient. pending: granted to nobody yet, and binding a supplier account delivers the whole package. delivered: the supplier organisation holds the grants now. expired: binding grants nothing, though a later revision of this request re-arms and delivers it. revoked: the owner took it back, binding grants nothing, and no later revision re-grants it, including through another directory site of the same supplier organisation" }, { "type": "null" } ] }, "note": { "type": "string", "description": "Present when there is something about this recipient's disclosure state to say: what binding will or will not deliver, and what revoking pendingDisclosureId does" } }, "required": [ "factoryId", "invitationId", "threadId", "supplierOrgId", "accountState", "grantedFileIds", "newRecipient" ] } }, "approvedBy": { "type": "string", "description": "uuid", "format": "uuid" }, "approvedAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time" } }, "required": [ "actionId", "apiProjectId", "projectId", "rfqId", "reviewSha256", "revision", "supersedes", "revisionNote", "apiContextSha256", "retainedActionSha256", "snapshotId", "snapshotSha256", "anonymised", "commercial", "fileIds", "factories", "approvedBy", "approvedAt", "publishedAt" ] }, "notification": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "email" ] }, "state": { "type": "string", "enum": [ "not_requested" ] }, "dispatchReceipt": { "type": "null" }, "note": { "type": "string" } }, "required": [ "channel", "state", "dispatchReceipt", "note" ] }, "replayed": { "type": "boolean", "description": "True when an identical reviewed revision was already published and nothing was written" }, "productionAuthorized": { "type": "boolean" }, "orderAuthorized": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "publication", "notification", "replayed", "productionAuthorized", "orderAuthorized", "requestId" ] } } } }, "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "publication": { "type": "object", "properties": { "actionId": { "type": "string", "description": "uuid" }, "apiProjectId": { "type": "string", "description": "uuid" }, "projectId": { "type": "string", "description": "uuid", "format": "uuid" }, "rfqId": { "type": "string", "description": "uuid", "format": "uuid" }, "reviewSha256": { "type": "string", "description": "The reviewed publication revision this request was published under" }, "revision": { "type": "integer", "description": "Which reviewed revision of this request this receipt is for, counting from 1. A correction published after the request is already out is the next revision: it reuses the same RFQ and every existing recipient's invitation and thread, and appends a row per recipient rather than rewriting the earlier revision." }, "supersedes": { "anyOf": [ { "type": "object", "properties": { "revision": { "type": "integer" }, "reviewSha256": { "type": "string" }, "publishedAt": { "type": "string", "format": "date-time" } }, "required": [ "revision", "reviewSha256", "publishedAt" ], "description": "The revision this one supersedes, or null on a first publication. A pointer, never a rewrite: the superseded revision keeps its own recipients, files, terms and publication-time grants." }, { "type": "null" } ] }, "revisionNote": { "type": "string", "description": "What this revision did to the supplier side, in words." }, "apiContextSha256": { "type": "string" }, "retainedActionSha256": { "type": "string" }, "snapshotId": { "type": "string", "description": "uuid", "format": "uuid" }, "snapshotSha256": { "type": "string" }, "anonymised": { "type": "boolean" }, "commercial": { "type": "object", "properties": { "currency": { "type": "string", "enum": [ "USD", "CNY" ] }, "incoterm": { "type": "string" }, "namedPlace": { "type": "string" }, "quoteBy": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "deliverTo": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "currency", "incoterm", "namedPlace", "quoteBy", "deliverTo" ] }, "fileIds": { "type": "array", "items": { "type": "string", "description": "uuid", "format": "uuid" }, "description": "Exactly the reviewed files. Granted at publication to each factory with a bound supplier account, and granted to an awaiting-account factory when a supplier account is later bound to it" }, "factories": { "type": "array", "items": { "type": "object", "properties": { "factoryId": { "type": "string", "description": "uuid", "format": "uuid" }, "invitationId": { "type": "string", "description": "uuid", "format": "uuid" }, "threadId": { "type": "string", "description": "uuid", "format": "uuid" }, "supplierOrgId": { "anyOf": [ { "type": "string", "description": "uuid", "format": "uuid" }, { "type": "null" } ] }, "accountState": { "type": "string", "enum": [ "bound", "awaiting_account" ] }, "newRecipient": { "type": "boolean", "description": "True when this revision is the first one this factory was a recipient of, which is every factory on a first publication. False means the invitation and thread are the ones it already had, so its thread history and any quote it already submitted are still attached to them, and it was told in that thread that the terms moved." }, "grantedFileIds": { "type": "array", "items": { "type": "string", "description": "uuid", "format": "uuid" }, "description": "The file grants this publication issued. Empty for a factory awaiting account setup, and also empty for a bound factory whose disclosure the owner has revoked, because a revision grants a revoked recipient nothing. It is not updated afterwards: binding a supplier account to a directory factory grants it the whole reviewed package without changing this list, so it is a record of publication-time state rather than an audit trail of current disclosure. Read pendingDisclosureState for that" }, "filesOnAccountBinding": { "type": "array", "items": { "type": "string", "description": "uuid", "format": "uuid" }, "description": "Present only when this factory is awaiting account setup AND its pending disclosure is still live: the reviewed files it will be granted when a supplier account is bound to it, with no further founder approval and no second review. These are not grants that exist yet. Absent once pendingDisclosureState is revoked, expired or delivered, because binding would then grant nothing" }, "filesOnAccountBindingExpireAt": { "anyOf": [ { "type": "string", "description": "Present alongside filesOnAccountBinding: the instant this pending disclosure lapses. Binding a supplier account after it grants nothing. Publishing a later revision of this request does re-arm it, because a revision carries a fresh owner approval naming this recipient; revoke pendingDisclosureId to stop that", "format": "date-time" }, { "type": "null" } ] }, "pendingDisclosureId": { "anyOf": [ { "type": "string", "description": "On EVERY recipient, whether or not it had a supplier account at publication time: the disclosure to read on GET /pending-disclosures, and the one the owner organisation revokes to take this package back from this factory. A recipient that was already bound has one too, recorded as delivered, because revoking it is the only way to delete the grants it already holds. Null only for a recipient this publication disclosed no files to", "format": "uuid" }, { "type": "null" } ] }, "pendingDisclosureState": { "anyOf": [ { "type": "string", "enum": [ "pending", "delivered", "expired", "revoked" ], "description": "On every recipient. pending: granted to nobody yet, and binding a supplier account delivers the whole package. delivered: the supplier organisation holds the grants now. expired: binding grants nothing, though a later revision of this request re-arms and delivers it. revoked: the owner took it back, binding grants nothing, and no later revision re-grants it, including through another directory site of the same supplier organisation" }, { "type": "null" } ] }, "note": { "type": "string", "description": "Present when there is something about this recipient's disclosure state to say: what binding will or will not deliver, and what revoking pendingDisclosureId does" } }, "required": [ "factoryId", "invitationId", "threadId", "supplierOrgId", "accountState", "grantedFileIds", "newRecipient" ] } }, "approvedBy": { "type": "string", "description": "uuid", "format": "uuid" }, "approvedAt": { "type": "string", "format": "date-time" }, "publishedAt": { "type": "string", "format": "date-time" } }, "required": [ "actionId", "apiProjectId", "projectId", "rfqId", "reviewSha256", "revision", "supersedes", "revisionNote", "apiContextSha256", "retainedActionSha256", "snapshotId", "snapshotSha256", "anonymised", "commercial", "fileIds", "factories", "approvedBy", "approvedAt", "publishedAt" ] }, "notification": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "email" ] }, "state": { "type": "string", "enum": [ "not_requested" ] }, "dispatchReceipt": { "type": "null" }, "note": { "type": "string" } }, "required": [ "channel", "state", "dispatchReceipt", "note" ] }, "replayed": { "type": "boolean", "description": "True when an identical reviewed revision was already published and nothing was written" }, "productionAuthorized": { "type": "boolean" }, "orderAuthorized": { "type": "boolean" }, "requestId": { "type": "string" } }, "required": [ "publication", "notification", "replayed", "productionAuthorized", "orderAuthorized", "requestId" ] } } } }, "400": { "description": "The selection could not be bound to the reviewed source and engineering", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Key or engineering grant does not authorize publication, or no stored founder approval covers this exact disclosure (publication_not_approved; details.field is recipients, files, terms, review_sha256 or approval)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Source, engineering or review changed, the revision drops a factory an earlier revision was already published to (publication_revision_recipient_removed; revoke it instead), no NDA is in force between this customer organisation and Maglev (nda_required; details.state says what the record holds), or the project has not recorded the release checks disclosure requires (publication_precondition; read eligibility on the review)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Retained engineering evidence is unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "x-scopes": [ "discover", "inspect", "interviews:write", "capabilities:own", "runs:own", "network:read", "contacts:read", "interactions:read", "knowledge:read", "lifecycle:read", "projects:write", "actions:write", "quotes:write", "shipping:read", "compliance:read", "approvals:write", "activity:read", "maglev:*" ], "x-lifecycle-stages": [ "mutual_nda", "manufacturer_nda", "product_strategy_session", "engineering_estimate", "statement_of_work", "mass_production_estimate", "rfq_and_quote", "quote_negotiation", "prd", "concept_architecture", "detailed_design_engineering", "prototype_and_testing", "evt", "dvt", "dfm", "npi", "tooling", "test_fixture_development", "supply_chain_setup", "assembly_process_and_line_setup", "pvt", "pre_production", "sample_approval", "factory_prioritisation", "material_coordination", "iqc", "programming_and_test", "oqc", "final_pack_out", "shipping", "tracking", "customs_and_import", "regulatory_and_certification", "compliance_documentation", "delivery" ], "x-action-kinds": [ { "kind": "nda_draft", "name": "NDA draft", "description": "Drafts a mutual NDA with a customer or a manufacturer NDA from Maglev's templates, filling only what the request supplies and listing every blank left for signature.", "availability": "available", "stageIds": [ "mutual_nda", "manufacturer_nda" ], "cost": "two_calls", "input": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "party": { "type": "string", "enum": [ "customer", "manufacturer" ] }, "counterpartyName": { "type": "string", "minLength": 1, "maxLength": 200 }, "counterpartyEntityZh": { "type": "string", "maxLength": 200 }, "counterpartyAddress": { "type": "string", "maxLength": 500 }, "counterpartyUscc": { "description": "Unified social credit code or company registration number", "type": "string", "maxLength": 64 }, "purpose": { "type": "string", "maxLength": 2000 }, "governingLaw": { "description": "Defaults to PRC for a manufacturer and Delaware for a customer", "type": "string", "maxLength": 100 }, "liquidatedDamagesUsd": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "party", "counterpartyName" ] }, "output": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "documentEn": { "type": "string", "description": "The complete agreement in markdown" }, "documentZh": { "description": "The Simplified Chinese text for a manufacturer NDA, else null", "type": [ "string", "null" ] }, "blanks": { "type": "array", "items": { "type": "string" }, "description": "Every field left as ______ for completion at signature" }, "clauseNotes": { "type": "array", "items": { "type": "string" }, "description": "Notes for counsel and for Sissi and Iana about clauses changed from the template or needing a decision" }, "assumptions": { "type": "array", "items": { "type": "string" }, "description": "What was assumed in order to write this draft" }, "openQuestions": { "type": "array", "items": { "type": "string" }, "description": "What only the founder, a factory or a lab can answer" }, "sources": { "type": "array", "items": { "type": "string" }, "description": "Repo paths of the passages actually relied on" } }, "required": [ "documentEn", "documentZh", "blanks", "clauseNotes", "assumptions", "openQuestions", "sources" ], "additionalProperties": false } }, { "kind": "strategy_brief", "name": "Strategy session brief", "description": "Prepares the agenda, questions and decisions that lock cost for a first product strategy session. Fee wording requires a published commercial policy; otherwise the draft asks for project-specific confirmation.", "availability": "available", "stageIds": [ "product_strategy_session" ], "cost": "one_call", "input": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "goals": { "maxItems": 30, "type": "array", "items": { "type": "string", "maxLength": 1000 } }, "constraints": { "maxItems": 30, "type": "array", "items": { "type": "string", "maxLength": 1000 } }, "questionsFromFounder": { "maxItems": 30, "type": "array", "items": { "type": "string", "maxLength": 1000 } } } }, "output": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agenda": { "type": "array", "items": { "type": "object", "properties": { "topic": { "type": "string" }, "minutes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Minutes to give the topic, or null if there is no basis to size it" }, "why": { "type": "string" } }, "required": [ "topic", "minutes", "why" ], "additionalProperties": false } }, "questionsMaglevWillAsk": { "type": "array", "items": { "type": "string" }, "description": "Questions a factory would ask before quoting, in the order Maglev will ask them" }, "decisionsThatLockCost": { "type": "array", "items": { "type": "object", "properties": { "decision": { "type": "string" }, "whyItLocksCost": { "type": "string" }, "whenToDecide": { "type": "string" } }, "required": [ "decision", "whyItLocksCost", "whenToDecide" ], "additionalProperties": false } }, "standardPartCandidates": { "type": "array", "items": { "type": "string" }, "description": "Parts of this product that could be off the shelf or a standard size, named only from what the project and request describe" }, "whatWeSayAboutFees": { "type": "string" }, "assumptions": { "type": "array", "items": { "type": "string" }, "description": "What was assumed in order to write this draft" }, "openQuestions": { "type": "array", "items": { "type": "string" }, "description": "What only the founder, a factory or a lab can answer" }, "sources": { "type": "array", "items": { "type": "string" }, "description": "Repo paths of the passages actually relied on" } }, "required": [ "agenda", "questionsMaglevWillAsk", "decisionsThatLockCost", "standardPartCandidates", "whatWeSayAboutFees", "assumptions", "openQuestions", "sources" ], "additionalProperties": false } }, { "kind": "engineering_estimate", "name": "Engineering estimate", "description": "Breaks a scope into work items with hour ranges and external one-off cost lines, kept apart from Maglev's fee, with a risk register.", "availability": "available", "stageIds": [ "engineering_estimate" ], "cost": "one_call", "input": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "scope": { "type": "string", "minLength": 1, "maxLength": 6000 }, "deliverables": { "maxItems": 40, "type": "array", "items": { "type": "string", "maxLength": 1000 } }, "knownRisks": { "maxItems": 40, "type": "array", "items": { "type": "string", "maxLength": 1000 } } }, "required": [ "scope" ] }, "output": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workBreakdown": { "type": "array", "items": { "type": "object", "properties": { "item": { "type": "string" }, "hoursLow": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hoursHigh": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "basis": { "type": "string", "description": "Where the hours come from, or why they are null" }, "role": { "type": "string", "description": "Who does the work: electrical engineer, mechanical engineer, firmware engineer, test engineer, contract manufacturer, lab, Maglev coordination" } }, "required": [ "item", "hoursLow", "hoursHigh", "basis", "role" ], "additionalProperties": false } }, "nreLines": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "category": { "type": "string", "description": "engineering, prototype_build, tooling, lab_testing, samples, travel, freight or other" }, "amountUsdLow": { "type": [ "number", "null" ] }, "amountUsdHigh": { "type": [ "number", "null" ] }, "basis": { "type": "string", "description": "The passage or request line the amount comes from, or what would produce a real number" } }, "required": [ "label", "category", "amountUsdLow", "amountUsdHigh", "basis" ], "additionalProperties": false } }, "maglevFee": { "type": "object", "properties": { "note": { "type": "string", "const": "charged separately and visibly; amount not set by this estimate" } }, "required": [ "note" ], "additionalProperties": false }, "riskRegister": { "type": "array", "items": { "type": "object", "properties": { "risk": { "type": "string" }, "impact": { "type": "string" }, "mitigation": { "type": "string" } }, "required": [ "risk", "impact", "mitigation" ], "additionalProperties": false } }, "assumptions": { "type": "array", "items": { "type": "string" }, "description": "What was assumed in order to write this draft" }, "openQuestions": { "type": "array", "items": { "type": "string" }, "description": "What only the founder, a factory or a lab can answer" }, "sources": { "type": "array", "items": { "type": "string" }, "description": "Repo paths of the passages actually relied on" } }, "required": [ "workBreakdown", "nreLines", "maglevFee", "riskRegister", "assumptions", "openQuestions", "sources" ], "additionalProperties": false } }, { "kind": "sow_draft", "name": "Statement of work draft", "description": "Drafts a statement of work with scope, deliverables, acceptance criteria, gates, split billing lines for factory amount and Maglev fee, and a stop at gate clause.", "availability": "available", "stageIds": [ "statement_of_work" ], "cost": "one_call", "input": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "scope": { "type": "string", "minLength": 1, "maxLength": 6000 }, "deliverables": { "minItems": 1, "maxItems": 40, "type": "array", "items": { "type": "string", "maxLength": 1000 } }, "milestones": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "dueHint": { "type": "string", "maxLength": 200 } }, "required": [ "name" ] } }, "paymentTerms": { "type": "string", "maxLength": 2000 } }, "required": [ "scope", "deliverables" ] }, "output": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "documentEn": { "type": "string", "description": "The statement of work in markdown" }, "gates": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "exitEvidence": { "type": "string" } }, "required": [ "name", "exitEvidence" ], "additionalProperties": false } }, "assumptions": { "type": "array", "items": { "type": "string" }, "description": "What was assumed in order to write this draft" }, "openQuestions": { "type": "array", "items": { "type": "string" }, "description": "What only the founder, a factory or a lab can answer" }, "sources": { "type": "array", "items": { "type": "string" }, "description": "Repo paths of the passages actually relied on" } }, "required": [ "documentEn", "gates", "assumptions", "openQuestions", "sources" ], "additionalProperties": false } }, { "kind": "prd_draft", "name": "PRD draft", "description": "Drafts a requirements register with acceptance criteria, priorities and TBD status, plus certification targets supported by the playbooks.", "availability": "available", "stageIds": [ "prd" ], "cost": "one_call", "input": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "useCase": { "type": "string", "minLength": 1, "maxLength": 4000 }, "users": { "type": "string", "maxLength": 2000 }, "mustHave": { "maxItems": 60, "type": "array", "items": { "type": "string", "maxLength": 1000 } }, "niceToHave": { "maxItems": 60, "type": "array", "items": { "type": "string", "maxLength": 1000 } }, "environment": { "type": "string", "maxLength": 2000 }, "interfaces": { "maxItems": 40, "type": "array", "items": { "type": "string", "maxLength": 500 } } }, "required": [ "useCase" ] }, "output": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requirements": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "REQ-001 style" }, "area": { "type": "string", "description": "function, performance, mechanical, electrical, power, interfaces, environment, safety, reliability, manufacturing, test, certification or packaging" }, "text": { "type": "string", "description": "The requirement; a number the request did not give is written as TBD, never guessed" }, "acceptance": { "type": "string", "description": "How it will be verified" }, "priority": { "type": "string", "enum": [ "must", "should", "could" ] }, "status": { "type": "string", "enum": [ "defined", "tbd" ] } }, "required": [ "id", "area", "text", "acceptance", "priority", "status" ], "additionalProperties": false } }, "certificationTargets": { "type": "array", "items": { "type": "object", "properties": { "market": { "type": "string" }, "mark": { "type": "string" }, "basis": { "type": "string", "description": "The passage that supports naming this target for this product" } }, "required": [ "market", "mark", "basis" ], "additionalProperties": false } }, "tbd": { "type": "array", "items": { "type": "string" }, "description": "Requirements and numbers still to be defined, with who defines them" }, "assumptions": { "type": "array", "items": { "type": "string" }, "description": "What was assumed in order to write this draft" }, "openQuestions": { "type": "array", "items": { "type": "string" }, "description": "What only the founder, a factory or a lab can answer" }, "sources": { "type": "array", "items": { "type": "string" }, "description": "Repo paths of the passages actually relied on" } }, "required": [ "requirements", "certificationTargets", "tbd", "assumptions", "openQuestions", "sources" ], "additionalProperties": false } }, { "kind": "architecture_review", "name": "Architecture review", "description": "Maps the product's subsystems to processes and flags lithium, radio, magnet, long lead, process floor, custom and regulated items, with the architecture risks that follow.", "availability": "available", "stageIds": [ "concept_architecture" ], "cost": "one_call", "input": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subsystems": { "maxItems": 40, "type": "array", "items": { "type": "string", "maxLength": 500 } }, "bomSummary": { "type": "string", "maxLength": 20000 }, "radios": { "maxItems": 10, "type": "array", "items": { "type": "string", "maxLength": 200 } }, "battery": { "type": "string", "maxLength": 1000 } } }, "output": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subsystems": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "process": { "anyOf": [ { "type": "string", "enum": [ "pcba", "injection_molding", "cnc", "sheet_metal", "die_casting", "wire_harness", "battery", "motor_actuator", "display", "camera", "power_adapter", "packaging", "off_the_shelf", "other" ] }, { "type": "null" } ], "description": "The process that makes it, or null if unclear" }, "flags": { "type": "array", "items": { "type": "string", "enum": [ "lithium", "radio", "magnet", "long_lead", "process_floor", "custom", "regulated" ] } }, "note": { "type": "string", "description": "One or two sentences for the founder about this subsystem; never a price or a lead time" } }, "required": [ "name", "process", "flags", "note" ], "additionalProperties": false } }, "risks": { "type": "array", "items": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" }, "description": "What was assumed in order to write this draft" }, "openQuestions": { "type": "array", "items": { "type": "string" }, "description": "What only the founder, a factory or a lab can answer" }, "sources": { "type": "array", "items": { "type": "string" }, "description": "Repo paths of the passages actually relied on" } }, "required": [ "subsystems", "risks", "assumptions", "openQuestions", "sources" ], "additionalProperties": false } }, { "kind": "dfm_review", "name": "DFM review", "description": "Reviews each part for manufacturability at the project's quantity, with process floor notes attributed to the factory that stated them and process recommendations using the crossover formula.", "availability": "available", "stageIds": [ "detailed_design_engineering", "dfm" ], "cost": "one_call", "input": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "parts": { "minItems": 1, "maxItems": 40, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "process": { "type": "string", "maxLength": 100 }, "material": { "type": "string", "maxLength": 200 }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "tolerance": { "type": "string", "maxLength": 200 }, "finish": { "type": "string", "maxLength": 200 } }, "required": [ "name" ] } } }, "required": [ "parts" ] }, "output": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "findings": { "type": "array", "items": { "type": "object", "properties": { "part": { "type": "string" }, "finding": { "type": "string" }, "severity": { "type": "string", "enum": [ "blocker", "major", "minor" ] }, "suggestion": { "type": "string" }, "processFloorNote": { "description": "The named factory's floor from the passages when one applies to this part and quantity, attributed with its date, else null", "type": [ "string", "null" ] } }, "required": [ "part", "finding", "severity", "suggestion", "processFloorNote" ], "additionalProperties": false } }, "processRecommendations": { "type": "array", "items": { "type": "object", "properties": { "part": { "type": "string" }, "recommendation": { "type": "string" }, "crossoverNote": { "type": "string" } }, "required": [ "part", "recommendation", "crossoverNote" ], "additionalProperties": false } }, "assumptions": { "type": "array", "items": { "type": "string" }, "description": "What was assumed in order to write this draft" }, "openQuestions": { "type": "array", "items": { "type": "string" }, "description": "What only the founder, a factory or a lab can answer" }, "sources": { "type": "array", "items": { "type": "string" }, "description": "Repo paths of the passages actually relied on" } }, "required": [ "findings", "processRecommendations", "assumptions", "openQuestions", "sources" ], "additionalProperties": false } }, { "kind": "test_plan", "name": "Test plan", "description": "Drafts EVT, DVT and PVT test plans with purpose, exit criteria, tests and the fixtures they need.", "availability": "available", "stageIds": [ "prototype_and_testing", "evt", "dvt", "test_fixture_development", "pvt" ], "cost": "one_call", "input": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "builds": { "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "evt", "dvt", "pvt" ] } }, "criticalFunctions": { "maxItems": 40, "type": "array", "items": { "type": "string", "maxLength": 500 } }, "environment": { "type": "string", "maxLength": 2000 } } }, "output": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "builds": { "type": "array", "items": { "type": "object", "properties": { "build": { "type": "string", "enum": [ "evt", "dvt", "pvt" ] }, "purpose": { "type": "string" }, "quantity": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "basis": { "type": "string", "description": "Where the quantity comes from, or why it is null" }, "exitCriteria": { "type": "array", "items": { "type": "string" } }, "tests": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "method": { "type": "string" }, "passCriteria": { "type": "string", "description": "Numeric only where the request gives the number, else the limit is TBD and who sets it" } }, "required": [ "name", "method", "passCriteria" ], "additionalProperties": false } } }, "required": [ "build", "purpose", "quantity", "basis", "exitCriteria", "tests" ], "additionalProperties": false } }, "fixtures": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "purpose": { "type": "string" }, "owner": { "type": "string", "enum": [ "factory", "customer", "unknown" ] } }, "required": [ "name", "purpose", "owner" ], "additionalProperties": false } }, "assumptions": { "type": "array", "items": { "type": "string" }, "description": "What was assumed in order to write this draft" }, "openQuestions": { "type": "array", "items": { "type": "string" }, "description": "What only the founder, a factory or a lab can answer" }, "sources": { "type": "array", "items": { "type": "string" }, "description": "Repo paths of the passages actually relied on" } }, "required": [ "builds", "fixtures", "assumptions", "openQuestions", "sources" ], "additionalProperties": false } }, { "kind": "npi_plan", "name": "NPI plan", "description": "Lays out the tooling, supply chain, fixture, line setup and pilot workstreams with dependencies, gates and long lead items, durations attributed to the factories that stated them.", "availability": "available", "stageIds": [ "npi", "tooling", "supply_chain_setup", "assembly_process_and_line_setup" ], "cost": "one_call", "input": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "targetShipDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "toolingNeeded": { "type": "boolean" }, "processes": { "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 100 } } } }, "output": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workstreams": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "step": { "type": "string" }, "dependsOn": { "type": "array", "items": { "type": "string" } }, "typicalDurationDays": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "basis": { "type": "string", "description": "The passage the duration comes from, attributed to the factory that stated it, or why it is null" } }, "required": [ "step", "dependsOn", "typicalDurationDays", "basis" ], "additionalProperties": false } } }, "required": [ "name", "steps" ], "additionalProperties": false } }, "gates": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "evidence": { "type": "string" } }, "required": [ "name", "evidence" ], "additionalProperties": false } }, "longLeadItems": { "type": "array", "items": { "type": "string" }, "description": "Only items the project, the request or a passage names" }, "assumptions": { "type": "array", "items": { "type": "string" }, "description": "What was assumed in order to write this draft" }, "openQuestions": { "type": "array", "items": { "type": "string" }, "description": "What only the founder, a factory or a lab can answer" }, "sources": { "type": "array", "items": { "type": "string" }, "description": "Repo paths of the passages actually relied on" } }, "required": [ "workstreams", "gates", "longLeadItems", "assumptions", "openQuestions", "sources" ], "additionalProperties": false } }, { "kind": "quality_plan", "name": "Quality plan", "description": "Drafts inspection points from incoming to pre shipment, sampling decisions requiring review, a golden sample gate and pack out checks.", "availability": "available", "stageIds": [ "iqc", "programming_and_test", "oqc", "final_pack_out" ], "cost": "one_call", "input": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "unitsPerBatch": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "criticalToQuality": { "maxItems": 40, "type": "array", "items": { "type": "string", "maxLength": 500 } }, "packaging": { "type": "string", "maxLength": 2000 } } }, "output": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "inspectionPoints": { "type": "array", "items": { "type": "object", "properties": { "stage": { "type": "string", "enum": [ "iqc", "ipqc", "fqc", "oqc", "psi" ] }, "what": { "type": "string" }, "method": { "type": "string" }, "sampling": { "type": "string", "description": "Every unit, first article plus per batch sample, or a stated sample; never a plan the quantity cannot support" } }, "required": [ "stage", "what", "method", "sampling" ], "additionalProperties": false } }, "aqlSuggestion": { "type": "object", "properties": { "level": { "type": [ "string", "null" ] }, "note": { "type": "string" } }, "required": [ "level", "note" ], "additionalProperties": false }, "goldenSampleGate": { "type": "array", "items": { "type": "string" }, "description": "What the golden sample must demonstrate and how it is tied to a revision" }, "packOutChecks": { "type": "array", "items": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" }, "description": "What was assumed in order to write this draft" }, "openQuestions": { "type": "array", "items": { "type": "string" }, "description": "What only the founder, a factory or a lab can answer" }, "sources": { "type": "array", "items": { "type": "string" }, "description": "Repo paths of the passages actually relied on" } }, "required": [ "inspectionPoints", "aqlSuggestion", "goldenSampleGate", "packOutChecks", "assumptions", "openQuestions", "sources" ], "additionalProperties": false } }, { "kind": "production_readiness", "name": "Production readiness review", "description": "Assesses readiness for a pilot build against Maglev's production readiness questionnaire, marking each item pass, gap or unknown with evidence and a next step.", "availability": "available", "stageIds": [ "pvt", "pre_production", "compliance_documentation" ], "cost": "one_call", "input": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "answers": { "description": "Free form answers to the readiness questionnaire, keyed by question id or topic", "type": "object", "propertyNames": { "type": "string", "maxLength": 200 }, "additionalProperties": { "type": "string", "maxLength": 4000 }, "maxProperties": 120 } } }, "output": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "area": { "type": "string" }, "question": { "type": "string" }, "status": { "type": "string", "enum": [ "pass", "gap", "unknown" ] }, "evidence": { "description": "The answer or intake text the status rests on, else null", "type": [ "string", "null" ] }, "nextStep": { "type": "string", "description": "Who does what to close it, or what file to link" } }, "required": [ "area", "question", "status", "evidence", "nextStep" ], "additionalProperties": false } }, "readinessSummary": { "type": "string" }, "blockers": { "type": "array", "items": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" }, "description": "What was assumed in order to write this draft" }, "openQuestions": { "type": "array", "items": { "type": "string" }, "description": "What only the founder, a factory or a lab can answer" }, "sources": { "type": "array", "items": { "type": "string" }, "description": "Repo paths of the passages actually relied on" } }, "required": [ "items", "readinessSummary", "blockers", "assumptions", "openQuestions", "sources" ], "additionalProperties": false } }, { "kind": "production_cost_estimate", "name": "Production cost estimate", "description": "Reads a BOM summary into cost drivers, one off lines and duty exposure, with a price band per quantity that stays null until a named factory has quoted on a date.", "availability": "available", "stageIds": [ "mass_production_estimate" ], "cost": "one_call", "input": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "bomSummary": { "type": "string", "minLength": 1, "maxLength": 20000 }, "quantities": { "default": [ 100, 300 ], "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "toolingExpected": { "type": "boolean" } }, "required": [ "bomSummary" ] }, "output": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "costDrivers": { "type": "array", "items": { "type": "object", "properties": { "line": { "type": "string" }, "whyItDrivesCost": { "type": "string" } }, "required": [ "line", "whyItDrivesCost" ], "additionalProperties": false }, "description": "The three to six lines where the money is" }, "priceBand": { "type": "array", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "lowUsd": { "type": [ "number", "null" ] }, "highUsd": { "type": [ "number", "null" ] }, "basis": { "type": "string" } }, "required": [ "quantity", "lowUsd", "highUsd", "basis" ], "additionalProperties": false } }, "oneOffLines": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "note": { "type": "string" } }, "required": [ "label", "note" ], "additionalProperties": false }, "description": "Tooling, setup, fixtures, certification, samples: what is one off and who owns it, no amounts unless a passage states one" }, "dutyExposure": { "type": "object", "properties": { "htsCandidates": { "type": "array", "items": { "type": "string" } }, "note": { "type": "string" } }, "required": [ "htsCandidates", "note" ], "additionalProperties": false }, "assumptions": { "type": "array", "items": { "type": "string" }, "description": "What was assumed in order to write this draft" }, "openQuestions": { "type": "array", "items": { "type": "string" }, "description": "What only the founder, a factory or a lab can answer" }, "sources": { "type": "array", "items": { "type": "string" }, "description": "Repo paths of the passages actually relied on" } }, "required": [ "costDrivers", "priceBand", "oneOffLines", "dutyExposure", "assumptions", "openQuestions", "sources" ], "additionalProperties": false } }, { "kind": "shipping_estimate", "name": "Shipping estimate", "description": "Chargeable weight, cost range, fuel surcharge range and transit days per mode (air express, air freight, ocean LCL) from cartons or totals, with the duty stack as rates. Deterministic.", "availability": "available", "stageIds": [ "shipping" ], "cost": "none", "input": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cartons": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "lengthCm": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 }, "widthCm": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 }, "heightCm": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 }, "weightKg": { "type": "number", "exclusiveMinimum": 0, "maximum": 2000 }, "count": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "lengthCm", "widthCm", "heightCm", "weightKg", "count" ] } }, "totals": { "type": "object", "properties": { "grossWeightKg": { "type": "number", "exclusiveMinimum": 0, "maximum": 100000 }, "volumeM3": { "type": "number", "minimum": 0, "maximum": 1000 } }, "required": [ "grossWeightKg", "volumeM3" ] }, "originCity": { "type": "string", "minLength": 2, "maxLength": 60 }, "destination": { "default": { "country": "US" }, "type": "object", "properties": { "country": { "type": "string", "const": "US" }, "postcode": { "type": "string", "maxLength": 10 }, "state": { "type": "string", "minLength": 2, "maxLength": 2 }, "city": { "type": "string", "maxLength": 60 } }, "required": [ "country" ] }, "modes": { "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "air_express", "air_freight", "ocean_lcl" ] } }, "declaredValueUsd": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100000000 }, { "type": "null" } ] }, "hts": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "productCategory": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "batteries": { "type": "string", "enum": [ "none", "contained", "packed_with", "standalone" ] } }, "anyOf": [ { "required": [ "cartons" ] }, { "required": [ "totals" ] } ], "description": "Provide cartons or totals. Cartons take precedence when both are present." }, "output": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} } }, { "kind": "landed_cost", "name": "Landed cost", "description": "Freight range plus the duty and fee stack on a declared value: MFN where known, Section 301 2018 list, Section 301 forced labour 12.5 percent, MPF, HMF for ocean; IEEPA and Section 122 shown at 0. Deterministic.", "availability": "available", "stageIds": [ "customs_and_import", "shipping" ], "cost": "none", "input": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cartons": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "lengthCm": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 }, "widthCm": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 }, "heightCm": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 }, "weightKg": { "type": "number", "exclusiveMinimum": 0, "maximum": 2000 }, "count": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "lengthCm", "widthCm", "heightCm", "weightKg", "count" ] } }, "totals": { "type": "object", "properties": { "grossWeightKg": { "type": "number", "exclusiveMinimum": 0, "maximum": 100000 }, "volumeM3": { "type": "number", "minimum": 0, "maximum": 1000 } }, "required": [ "grossWeightKg", "volumeM3" ] }, "originCity": { "type": "string", "minLength": 2, "maxLength": 60 }, "destination": { "default": { "country": "US" }, "type": "object", "properties": { "country": { "type": "string", "const": "US" }, "postcode": { "type": "string", "maxLength": 10 }, "state": { "type": "string", "minLength": 2, "maxLength": 2 }, "city": { "type": "string", "maxLength": 60 } }, "required": [ "country" ] }, "modes": { "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "air_express", "air_freight", "ocean_lcl" ] } }, "declaredValueUsd": { "type": "number", "minimum": 0, "maximum": 100000000 }, "hts": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "productCategory": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "batteries": { "type": "string", "enum": [ "none", "contained", "packed_with", "standalone" ] } }, "required": [ "declaredValueUsd" ], "anyOf": [ { "required": [ "cartons" ] }, { "required": [ "totals" ] } ], "description": "Provide cartons or totals. Cartons take precedence when both are present." }, "output": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} } }, { "kind": "customs_profile", "name": "Customs profile", "description": "HTS candidate headings with reasoning, the duty stack for the chosen or leading candidate, the document checklist from playbook 1.5 to 1.9 and 1.1 to 1.3, and an analyst summary in English and Chinese. Maglev records candidates and never chooses the code.", "availability": "available", "stageIds": [ "customs_and_import" ], "cost": "one_call", "input": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "product": { "type": "string", "minLength": 2, "maxLength": 200 }, "description": { "type": "string", "minLength": 2, "maxLength": 2000 }, "materials": { "type": "string", "maxLength": 400 }, "function": { "type": "string", "maxLength": 400 }, "hts": { "description": "The importer's working code, if one exists; otherwise the first candidate is used for the stack as an illustration", "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "declaredValueUsd": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100000000 }, { "type": "null" } ] }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "modes": { "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "air_express", "air_freight", "ocean_lcl" ] } }, "flags": { "default": [], "maxItems": 8, "type": "array", "items": { "type": "string", "enum": [ "radio", "lithium", "ocean", "magnet", "semiconductors", "steel", "aluminium", "copper" ] } } }, "required": [ "product", "description" ] }, "output": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} } }, { "kind": "compliance_path", "name": "Compliance path", "description": "The certification and labelling requirements for a product and its markets (FCC SDoC or Certification, UL or ETL, UN38.3, FDA laser, CPSIA, CE, RED, RoHS, REACH, Prop 65, origin marking) from Maglev's playbook rules, with a plain language explanation in English and Chinese.", "availability": "available", "stageIds": [ "regulatory_and_certification", "compliance_documentation" ], "cost": "one_call", "input": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "product": { "type": "string", "minLength": 2, "maxLength": 400 }, "markets": { "default": [ "US" ], "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 8 } }, "radios": { "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 40 } }, "moduleIsPreCertified": { "type": [ "boolean", "null" ] }, "battery": { "default": "none", "type": "string", "enum": [ "none", "liion_contained", "liion_pack", "other" ] }, "mainsPowered": { "type": "boolean" }, "laser": { "type": "boolean" }, "childrensProduct": { "type": "boolean" }, "medical": { "type": "boolean" } }, "required": [ "product" ] }, "output": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} } }, { "kind": "shipment_tracking", "name": "Shipment tracking", "description": "Latest status and events for a tracking number through DHL's unified tracking API or 17TRACK, whichever has a credential. Without one, returns a planned payload naming the missing key.", "availability": "available", "stageIds": [ "tracking", "delivery" ], "cost": "none", "input": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "carrier": { "default": "auto", "type": "string", "enum": [ "dhl", "17track", "auto" ] }, "trackingNumber": { "type": "string", "pattern": "^[A-Za-z0-9-]{6,40}$" } }, "required": [ "trackingNumber" ] }, "output": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} } }, { "kind": "shipping_booking", "name": "Freight booking", "description": "Asks Maglev to book freight with a DG capable forwarder for this project. Returns the calculator estimate now and a work item a Maglev person picks up; nothing is booked by the API.", "availability": "coordinated", "stageIds": [ "shipping" ], "cost": "none", "input": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cartons": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "lengthCm": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 }, "widthCm": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 }, "heightCm": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000 }, "weightKg": { "type": "number", "exclusiveMinimum": 0, "maximum": 2000 }, "count": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "required": [ "lengthCm", "widthCm", "heightCm", "weightKg", "count" ] } }, "totals": { "type": "object", "properties": { "grossWeightKg": { "type": "number", "exclusiveMinimum": 0, "maximum": 100000 }, "volumeM3": { "type": "number", "minimum": 0, "maximum": 1000 } }, "required": [ "grossWeightKg", "volumeM3" ] }, "originCity": { "type": "string", "minLength": 2, "maxLength": 60 }, "destination": { "default": { "country": "US" }, "type": "object", "properties": { "country": { "type": "string", "const": "US" }, "postcode": { "type": "string", "maxLength": 10 }, "state": { "type": "string", "minLength": 2, "maxLength": 2 }, "city": { "type": "string", "maxLength": 60 } }, "required": [ "country" ] }, "modes": { "minItems": 1, "maxItems": 3, "type": "array", "items": { "type": "string", "enum": [ "air_express", "air_freight", "ocean_lcl" ] } }, "declaredValueUsd": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100000000 }, { "type": "null" } ] }, "hts": { "anyOf": [ { "type": "string", "maxLength": 20 }, { "type": "null" } ] }, "productCategory": { "anyOf": [ { "type": "string", "maxLength": 100 }, { "type": "null" } ] }, "batteries": { "type": "string", "enum": [ "none", "contained", "packed_with", "standalone" ] }, "preferredMode": { "type": "string", "enum": [ "air_express", "air_freight", "ocean_lcl" ] }, "incoterm": { "default": "unknown", "type": "string", "enum": [ "FOB", "EXW", "DAP", "DDP", "unknown" ] }, "cargoReadyDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "deliveryAddress": { "type": "string", "maxLength": 400 }, "notes": { "type": "string", "maxLength": 2000 } }, "anyOf": [ { "required": [ "cartons" ] }, { "required": [ "totals" ] } ], "description": "Provide cartons or totals. Cartons take precedence when both are present." }, "output": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": {} } }, { "kind": "quote_request", "name": "Request quotes", "description": "Shortlists factories and drafts one anonymised RFQ, in English and Simplified Chinese, as a held delivery per factory. Nothing is sent.", "availability": "available", "stageIds": [ "rfq_and_quote", "tooling", "supply_chain_setup" ], "cost": "one_call", "input": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "scope": { "type": "string", "enum": [ "pcba", "box_build", "mechanical_part", "tooling", "full_product", "mixed" ] }, "parts": { "minItems": 1, "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "What the part is, as the founder names it" }, "process": { "description": "The manufacturing process, when known", "type": "string", "enum": [ "pcba", "injection_molding", "cnc", "sheet_metal", "die_casting", "wire_harness", "battery", "motor_actuator", "display", "camera", "power_adapter", "packaging", "off_the_shelf", "other" ] }, "material": { "type": "string", "maxLength": 200 }, "finish": { "type": "string", "maxLength": 200 }, "quantityPerUnit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "notes": { "type": "string", "maxLength": 1000 } }, "required": [ "name" ] } }, "quantities": { "description": "Explicit alternative quantity bands. Omit to use the confirmed current project quantity. Planned pilots and forecasts never become quote bands automatically.", "minItems": 1, "maxItems": 6, "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0, "maximum": 10000000 } }, "incoterm": { "description": "Requested trade term. Omit when unknown; the supplier will be asked to clarify it.", "type": "string", "enum": [ "EXW", "FCA", "CPT", "CIP", "DAP", "DPU", "DDP", "FAS", "FOB", "CFR", "CIF" ] }, "quoteBy": { "description": "The date we would like the quote by, YYYY-MM-DD", "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "drawingsStatus": { "default": "none_yet", "type": "string", "enum": [ "none_yet", "drawings_attached", "sample_available", "drawings_and_sample" ] }, "dfmQuestions": { "description": "Design questions the founder wants the factory's view on", "type": "string", "maxLength": 2000 }, "anonymised": { "default": true, "description": "Keep the founder's company and product out of the RFQ; the default and the recommended setting", "type": "boolean" }, "factoryIds": { "description": "Factory UUIDs or directory IDs (mfg-, int-, eng-) for held delivery drafts. Legacy names must resolve uniquely. When absent or empty the action shortlists from the directory.", "maxItems": 5, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "matchLimit": { "default": 3, "description": "Automatic shortlist size after ranking up to 12 matching directory records; explicit factoryIds retain all resolved selections", "type": "integer", "minimum": 1, "maximum": 5 }, "priority": { "description": "Buyer preference carried into the RFQ. Directory order is preserved because comparable price, quality and delivery evidence is unavailable.", "type": "string", "enum": [ "price", "lead_time", "quality" ] } }, "required": [ "scope", "parts" ] }, "output": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "shortlist": { "type": "array", "items": { "type": "object", "properties": { "factoryId": { "type": "string" }, "directoryId": { "type": [ "string", "null" ] }, "nameEn": { "type": "string" }, "nameZh": { "type": [ "string", "null" ] }, "why": { "type": "array", "items": { "type": "string" } } }, "required": [ "factoryId", "directoryId", "nameEn", "nameZh", "why" ], "additionalProperties": false } }, "unresolvedFactoryIds": { "type": "array", "items": { "type": "string" }, "description": "Ids the caller passed that matched no factory record" }, "rfq": { "anyOf": [ { "type": "object", "properties": { "en": { "type": "string" }, "zh": { "type": "string" } }, "required": [ "en", "zh" ], "additionalProperties": false }, { "type": "null" } ] }, "subjectZh": { "type": [ "string", "null" ] }, "quantities": { "type": "array", "items": { "type": "number" } }, "incoterm": { "type": [ "string", "null" ] }, "intentContext": { "type": "object", "properties": { "projectVersion": { "type": "string" }, "intent": { "anyOf": [ { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1 }, "current": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "samples", "pilot", "production", "unknown" ] }, "quantity": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 10000000 }, { "type": "null" } ] }, "unit": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] }, "configuration": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] }, "revision": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] }, "confirmation": { "type": "string", "enum": [ "unconfirmed", "caller_confirmed" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "caller", "file", "interview" ] }, "reference": { "type": "string", "minLength": 1, "maxLength": 800 }, "quote": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] } }, "required": [ "kind", "reference", "quote" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "purpose", "quantity", "unit", "configuration", "revision", "confirmation", "source" ], "additionalProperties": false }, "plannedPilot": { "anyOf": [ { "type": "object", "properties": { "quantity": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 10000000 }, { "type": "null" } ] }, "unit": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] }, "period": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "caller", "file", "interview" ] }, "reference": { "type": "string", "minLength": 1, "maxLength": 800 }, "quote": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] } }, "required": [ "kind", "reference", "quote" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "quantity", "unit", "period", "source" ], "additionalProperties": false }, { "type": "null" } ] }, "forecast": { "anyOf": [ { "type": "object", "properties": { "quantity": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 10000000 }, { "type": "null" } ] }, "unit": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] }, "period": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "caller", "file", "interview" ] }, "reference": { "type": "string", "minLength": 1, "maxLength": 800 }, "quote": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] } }, "required": [ "kind", "reference", "quote" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "quantity", "unit", "period", "source" ], "additionalProperties": false }, { "type": "null" } ] }, "requirements": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "location", "quality", "material", "inspection", "deadline", "other" ] }, "detail": { "type": "string", "minLength": 1, "maxLength": 800 }, "strength": { "type": "string", "enum": [ "hard", "preference" ] }, "confirmation": { "type": "string", "enum": [ "unconfirmed", "caller_confirmed" ] }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "caller", "file", "interview" ] }, "reference": { "type": "string", "minLength": 1, "maxLength": 800 }, "quote": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] } }, "required": [ "kind", "reference", "quote" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "kind", "detail", "strength", "confirmation", "source" ], "additionalProperties": false } }, "priorities": { "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "quality", "price", "lead_time", "scale", "location" ] } }, "prioritySource": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "caller", "file", "interview" ] }, "reference": { "type": "string", "minLength": 1, "maxLength": 800 }, "quote": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 800 }, { "type": "null" } ] } }, "required": [ "kind", "reference", "quote" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "schemaVersion", "current", "plannedPilot", "forecast", "requirements", "priorities", "prioritySource" ], "additionalProperties": false }, { "type": "null" } ] }, "currentQuantity": { "type": [ "number", "null" ] }, "quantitySource": { "type": "string", "enum": [ "manufacturing_intent", "project", "explicit_quote_band", "unknown" ] } }, "required": [ "projectVersion", "intent", "currentQuantity", "quantitySource" ], "additionalProperties": false }, "missingFields": { "type": "array", "items": { "type": "string" } }, "reviewRequirements": { "type": "array", "items": { "type": "string" } }, "priorityRanking": { "type": "string", "const": "not_verified" }, "priority": { "anyOf": [ { "type": "string", "enum": [ "price", "lead_time", "quality" ] }, { "type": "null" } ] }, "whatHappensNext": { "type": "array", "items": { "type": "string" } } }, "required": [ "shortlist", "unresolvedFactoryIds", "rfq", "subjectZh", "quantities", "incoterm", "intentContext", "missingFields", "reviewRequirements", "priorityRanking", "priority", "whatHappensNext" ], "additionalProperties": false } }, { "kind": "quote_record", "name": "Record a quote", "description": "Normalises a factory's reply into price breaks, tooling, mould ownership, lead times, MOQ, terms and exclusions, with verbatim evidence and the flags that stop it being compared. Translates Chinese to English and keeps the original.", "availability": "available", "stageIds": [ "rfq_and_quote" ], "cost": "one_call", "input": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "factoryId": { "type": "string", "minLength": 1, "maxLength": 120 }, "factoryName": { "type": "string", "minLength": 1, "maxLength": 200 }, "quoteText": { "type": "string", "minLength": 1, "maxLength": 12000, "description": "The factory's reply pasted verbatim, in any language" }, "currency": { "description": "Only if the caller knows the currency and the text does not state it", "type": "string", "enum": [ "USD", "CNY" ] }, "receivedOn": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } }, "required": [ "quoteText" ] }, "output": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "factory": { "anyOf": [ { "type": "object", "properties": { "factoryId": { "type": [ "string", "null" ] }, "directoryId": { "type": [ "string", "null" ] }, "nameEn": { "type": "string" }, "nameZh": { "type": [ "string", "null" ] } }, "required": [ "factoryId", "directoryId", "nameEn", "nameZh" ], "additionalProperties": false }, { "type": "null" } ] }, "factoryResolved": { "type": "boolean" }, "receivedOn": { "type": [ "string", "null" ] }, "originalText": { "type": "string" }, "originalLanguage": { "type": "string", "enum": [ "zh", "en" ] }, "translatedText": { "type": [ "string", "null" ] }, "quote": { "type": "object", "properties": { "priceBreaks": { "type": "array", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "unitPrice": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "enum": [ "USD", "CNY", "unknown" ], "description": "The currency the factory wrote. unknown when the text names none." } }, "required": [ "quantity", "unitPrice", "currency" ], "additionalProperties": false } }, "toolingCost": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "toolingCurrency": { "anyOf": [ { "type": "string", "enum": [ "USD", "CNY", "unknown" ] }, { "type": "null" } ] }, "toolingType": { "description": "What the factory called the tool, in its words: 718H rapid tool, aluminium bridge tool, steel production tool, stencil, fixture", "type": [ "string", "null" ] }, "moldOwnership": { "type": "string", "enum": [ "customer", "factory", "unknown" ] }, "sampleCost": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "sampleLeadDays": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "toolingLeadDays": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "productionLeadDays": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "moq": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "paymentTerms": { "type": [ "string", "null" ] }, "validUntil": { "type": [ "string", "null" ] }, "incoterm": { "type": [ "string", "null" ] }, "quoteUnit": { "type": "string", "enum": [ "piece", "set", "unknown" ] }, "taxIncluded": { "type": "string", "enum": [ "included", "excluded", "unknown" ] }, "exclusions": { "type": "array", "items": { "type": "string" }, "description": "What the factory said the price does not include" }, "dfmNotes": { "type": [ "string", "null" ] }, "regulatoryClaims": { "type": "array", "items": { "type": "string" }, "description": "Anything the factory said about certification, customs or law, recorded as its claim and not as fact" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "quote": { "type": "string" } }, "required": [ "field", "quote" ], "additionalProperties": false }, "description": "Verbatim substrings of the quote text that support each recorded field" } }, "required": [ "priceBreaks", "toolingCost", "toolingCurrency", "toolingType", "moldOwnership", "sampleCost", "sampleLeadDays", "toolingLeadDays", "productionLeadDays", "moq", "paymentTerms", "validUntil", "incoterm", "quoteUnit", "taxIncluded", "exclusions", "dfmNotes", "regulatoryClaims", "evidence" ], "additionalProperties": false }, "comparisonFlags": { "type": "array", "items": { "type": "string" } }, "evidenceDropped": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Evidence items the model offered that were not verbatim substrings of the quote text, removed" }, "feeLine": { "type": "string" } }, "required": [ "factory", "factoryResolved", "receivedOn", "originalText", "originalLanguage", "translatedText", "quote", "comparisonFlags", "evidenceDropped", "feeLine" ], "additionalProperties": false } }, { "kind": "quote_negotiation", "name": "Negotiate a quote", "description": "Takes a quote apart the way the runbook does: what the MOQ recovers, the batches totalled, tooling as avoidable rather than amortised, basis confirmed, an honest way to say no. Drafts the counter message in Chinese and English as a held delivery.", "availability": "available", "stageIds": [ "quote_negotiation" ], "cost": "one_call", "input": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "quote": { "description": "The normalised quote from quote_record", "type": "object", "properties": { "priceBreaks": { "type": "array", "items": { "type": "object", "properties": { "quantity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "unitPrice": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "enum": [ "USD", "CNY", "unknown" ], "description": "The currency the factory wrote. unknown when the text names none." } }, "required": [ "quantity", "unitPrice", "currency" ] } }, "toolingCost": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "toolingCurrency": { "anyOf": [ { "type": "string", "enum": [ "USD", "CNY", "unknown" ] }, { "type": "null" } ] }, "toolingType": { "description": "What the factory called the tool, in its words: 718H rapid tool, aluminium bridge tool, steel production tool, stencil, fixture", "type": [ "string", "null" ] }, "moldOwnership": { "type": "string", "enum": [ "customer", "factory", "unknown" ] }, "sampleCost": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "sampleLeadDays": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "toolingLeadDays": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "productionLeadDays": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "moq": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "paymentTerms": { "type": [ "string", "null" ] }, "validUntil": { "type": [ "string", "null" ] }, "incoterm": { "type": [ "string", "null" ] }, "quoteUnit": { "type": "string", "enum": [ "piece", "set", "unknown" ] }, "taxIncluded": { "type": "string", "enum": [ "included", "excluded", "unknown" ] }, "exclusions": { "type": "array", "items": { "type": "string" }, "description": "What the factory said the price does not include" }, "dfmNotes": { "type": [ "string", "null" ] }, "regulatoryClaims": { "type": "array", "items": { "type": "string" }, "description": "Anything the factory said about certification, customs or law, recorded as its claim and not as fact" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "quote": { "type": "string" } }, "required": [ "field", "quote" ] }, "description": "Verbatim substrings of the quote text that support each recorded field" } } }, "quoteText": { "description": "Or the factory's reply as free text", "type": "string", "minLength": 1, "maxLength": 12000 }, "targets": { "default": {}, "type": "object", "properties": { "unitPriceUsd": { "type": "number", "exclusiveMinimum": 0 }, "leadTimeDays": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "moq": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "toolingOwnership": { "type": "string", "const": "customer" } } }, "totalPlannedUnitsAcrossBatches": { "description": "Every batch the founder has told us about, added together", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "leverage": { "description": "What we are authorised to offer: an early deposit, a follow on order, flexibility on a date", "maxItems": 8, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "factoryId": { "type": "string", "minLength": 1, "maxLength": 120 }, "factoryName": { "type": "string", "minLength": 1, "maxLength": 200 }, "tone": { "default": "warm", "type": "string", "enum": [ "warm", "direct" ] } }, "anyOf": [ { "required": [ "quote" ] }, { "required": [ "quoteText" ] } ] }, "output": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "strategy": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "point": { "type": "string" }, "why": { "type": "string" }, "ask": { "type": "string" } }, "required": [ "point", "why", "ask" ], "additionalProperties": false } }, "counterMessageZh": { "type": "string" }, "counterMessageEn": { "type": "string" }, "doNotSay": { "type": "array", "items": { "type": "string" } }, "expectedResponses": { "type": "array", "items": { "type": "object", "properties": { "ifTheySay": { "type": "string" }, "thenWe": { "type": "string" } }, "required": [ "ifTheySay", "thenWe" ], "additionalProperties": false } }, "factory": { "anyOf": [ { "type": "object", "properties": { "factoryId": { "type": [ "string", "null" ] }, "directoryId": { "type": [ "string", "null" ] }, "nameEn": { "type": "string" }, "nameZh": { "type": [ "string", "null" ] } }, "required": [ "factoryId", "directoryId", "nameEn", "nameZh" ], "additionalProperties": false }, { "type": "null" } ] }, "factoryResolved": { "type": "boolean" }, "arithmetic": { "anyOf": [ { "type": "object", "properties": { "plannedTotal": { "type": "number" }, "moq": { "type": "number" }, "gap": { "type": "number", "description": "MOQ minus the planned total; zero or negative means the batches already clear the minimum" }, "ratio": { "type": "number", "description": "MOQ divided by the planned total" }, "reading": { "type": "string" } }, "required": [ "plannedTotal", "moq", "gap", "ratio", "reading" ], "additionalProperties": false }, { "type": "null" } ] }, "subjectZh": { "type": "string" } }, "required": [ "strategy", "counterMessageZh", "counterMessageEn", "doNotSay", "expectedResponses", "factory", "factoryResolved", "arithmetic", "subjectZh" ], "additionalProperties": false } }, { "kind": "factory_prioritisation", "name": "Ask for priority", "description": "Drafts a courteous bilingual scheduling request, offering only what the input authorises. Held for approval; nothing is sent.", "availability": "available", "stageIds": [ "factory_prioritisation" ], "cost": "one_call", "input": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "factoryId": { "type": "string", "minLength": 1, "maxLength": 120 }, "factoryName": { "type": "string", "minLength": 1, "maxLength": 200 }, "orderSummary": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "What the order is, in a sentence or two" }, "dateThatMatters": { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "whyItMatters": { "type": "string", "minLength": 1, "maxLength": 1000 }, "offers": { "description": "What we are authorised to offer: an early deposit, flexibility on another date, a follow on order", "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "currentPromise": { "description": "What the factory has promised so far, if anything", "type": "string", "maxLength": 500 } }, "required": [ "orderSummary", "dateThatMatters", "whyItMatters" ] }, "output": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "messageZh": { "type": "string" }, "messageEn": { "type": "string" }, "whatWeOffer": { "type": "array", "items": { "type": "string" }, "description": "The exact authorised offers supplied by the caller; empty when none were supplied" }, "whatNotToPromise": { "type": "array", "items": { "type": "string" } }, "factory": { "anyOf": [ { "type": "object", "properties": { "factoryId": { "type": [ "string", "null" ] }, "directoryId": { "type": [ "string", "null" ] }, "nameEn": { "type": "string" }, "nameZh": { "type": [ "string", "null" ] } }, "required": [ "factoryId", "directoryId", "nameEn", "nameZh" ], "additionalProperties": false }, { "type": "null" } ] }, "factoryResolved": { "type": "boolean" }, "subjectZh": { "type": "string" } }, "required": [ "messageZh", "messageEn", "whatWeOffer", "whatNotToPromise", "factory", "factoryResolved", "subjectZh" ], "additionalProperties": false } }, { "kind": "status_check", "name": "Check progress", "description": "Drafts a short Chinese progress check that asks for dates and evidence on a milestone, with the checklist of facts the reply should contain. Held for approval; nothing is sent.", "availability": "available", "stageIds": [ "material_coordination", "tracking" ], "cost": "one_call", "input": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "factoryId": { "type": "string", "minLength": 1, "maxLength": 120 }, "factoryName": { "type": "string", "minLength": 1, "maxLength": 200 }, "orderSummary": { "type": "string", "minLength": 1, "maxLength": 2000 }, "milestone": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The milestone to check: material arrival, T1 shots, first article, packing" }, "lastUpdate": { "description": "What the factory last told us, and when", "type": "string", "maxLength": 1000 }, "questions": { "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 300 } } }, "required": [ "orderSummary", "milestone" ] }, "output": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "messageZh": { "type": "string" }, "messageEn": { "type": "string" }, "checklist": { "minItems": 1, "type": "array", "items": { "type": "string" } }, "factory": { "anyOf": [ { "type": "object", "properties": { "factoryId": { "type": [ "string", "null" ] }, "directoryId": { "type": [ "string", "null" ] }, "nameEn": { "type": "string" }, "nameZh": { "type": [ "string", "null" ] } }, "required": [ "factoryId", "directoryId", "nameEn", "nameZh" ], "additionalProperties": false }, { "type": "null" } ] }, "factoryResolved": { "type": "boolean" }, "subjectZh": { "type": "string" } }, "required": [ "messageZh", "messageEn", "checklist", "factory", "factoryResolved", "subjectZh" ], "additionalProperties": false } } ], "x-maglev-source": { "repository": "Maglev-Inc/maglev-platform", "commit": "0319a80e690c0116a119195d08a7de54d217abbd", "exportedContractCommit": "0319a80e690c0116a119195d08a7de54d217abbd", "priorAnnotationSourceCommit": "c0b165aadd055a954be15f0db7122ae1971ccb9b", "deploymentCommitVerified": true, "catalogBaselineCommit": "c375c85", "expandedSourceSha256": "829d14ad5df4db88d41a84745da72b4cd8b6cfd02f8d2aa3c9ee5d46eca753fb", "sourceSha256": "0dfc26544c55247e1db64e8ae80abc53a38ce2e27fda76f75ed968ae347726ff", "reviewed": "2026-09-22", "annotationVersion": "7" } }