{"openapi":"3.1.0","info":{"title":"NEXUS Engineering API","version":"0.2.0","description":"Alpha. Paths, methods and auth are formal; body schemas are in the API reference."},"security":[{"bearer":[]}],"paths":{"/healthz":{"get":{"summary":"Liveness","tags":["ops"],"parameters":[],"security":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/readyz":{"get":{"summary":"Readiness (queries the database)","tags":["ops"],"parameters":[],"security":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/platform":{"get":{"summary":"Contract version and installed products","tags":["ops"],"parameters":[],"security":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/register-organization":{"post":{"summary":"Create an organization and its first admin","tags":["auth"],"parameters":[],"security":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/login":{"post":{"summary":"Exchange credentials for a session token","tags":["auth"],"parameters":[],"security":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/oidc/status":{"get":{"summary":"Whether single sign-on is configured","tags":["auth"],"parameters":[],"security":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/oidc/start":{"get":{"summary":"Begin OpenID Connect sign-in (redirects to the provider)","tags":["auth"],"parameters":[],"security":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/oidc/callback":{"get":{"summary":"Complete OpenID Connect sign-in; sets the session cookie and redirects","tags":["auth"],"parameters":[],"security":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/logout":{"post":{"summary":"Revoke the current session","tags":["auth"],"parameters":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/mfa":{"get":{"summary":"Multi-factor status for the current user","tags":["auth"],"parameters":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/mfa/enroll":{"post":{"summary":"Start TOTP enrollment (returns the secret once)","tags":["auth"],"parameters":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/mfa/confirm":{"post":{"summary":"Confirm enrollment with a code; returns one-time recovery codes","tags":["auth"],"parameters":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/auth/mfa/disable":{"post":{"summary":"Turn MFA off (needs a valid code or recovery code)","tags":["auth"],"parameters":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/me":{"get":{"summary":"Current user and entitlements","tags":["auth"],"parameters":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/products":{"get":{"summary":"Installed products with entitlement and dependency info","tags":["admin"],"parameters":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/users":{"get":{"summary":"List organization users","tags":["admin"],"parameters":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a user (org admin)","tags":["admin"],"parameters":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/entitlements":{"get":{"summary":"List product entitlements","tags":["admin"],"parameters":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/entitlements/{product}":{"put":{"summary":"Grant a product entitlement (org admin)","tags":["admin"],"parameters":[{"name":"product","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Revoke a product entitlement (org admin)","tags":["admin"],"parameters":[{"name":"product","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects":{"get":{"summary":"List projects you belong to","tags":["projects"],"parameters":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a project","tags":["projects"],"parameters":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/import":{"post":{"summary":"Import a project package as a new project","tags":["projects"],"parameters":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{projectId}":{"get":{"summary":"Get a project","tags":["projects"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{projectId}/export":{"get":{"summary":"Export a project package (owner)","tags":["projects"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{projectId}/members":{"get":{"summary":"List project members","tags":["projects"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Add or change a member's role","tags":["projects"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{projectId}/objects":{"get":{"summary":"List objects","tags":["objects"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create an object","tags":["objects"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{projectId}/objects/{objectId}":{"get":{"summary":"Get the current revision","tags":["objects"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"objectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Write a new revision (expectedRevision required)","tags":["objects"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"objectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{projectId}/objects/{objectId}/revisions":{"get":{"summary":"Revision history","tags":["objects"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"objectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{projectId}/objects/{objectId}/revisions/{revision}":{"get":{"summary":"Get one revision","tags":["objects"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"objectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"revision","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{projectId}/objects/{objectId}/transition":{"post":{"summary":"Change lifecycle state","tags":["objects"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"objectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{projectId}/objects/{objectId}/integrity":{"get":{"summary":"Verify stored checksums","tags":["objects"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"objectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{projectId}/objects/{objectId}/references":{"get":{"summary":"References held by an object, resolved (current/changed/unavailable)","tags":["references"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"objectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a revision-pinned reference","tags":["references"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"objectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{projectId}/objects/{objectId}/dependents":{"get":{"summary":"Objects that reference this object","tags":["references"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"objectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{projectId}/references/{referenceId}":{"put":{"summary":"Explicitly re-pin a reference to another revision","tags":["references"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"referenceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{projectId}/events":{"get":{"summary":"Change feed (afterSeq cursor)","tags":["references"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/ai/tools":{"get":{"summary":"Registered AI tools with risk tiers and required permissions","tags":["ai"],"parameters":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{projectId}/ai/proposals":{"post":{"summary":"An agent proposes a tool call (low risk runs now; others await a human)","tags":["ai"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List AI proposals","tags":["ai"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{projectId}/ai/proposals/{proposalId}":{"get":{"summary":"Get one AI proposal with preview and result","tags":["ai"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"proposalId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{projectId}/ai/proposals/{proposalId}/decision":{"post":{"summary":"Approve (runs the tool as you) or reject a proposal","tags":["ai"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"proposalId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/projects/{projectId}/sync":{"post":{"summary":"Push offline operations (idempotent; per-operation applied/conflict/rejected/invalid)","tags":["sync"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"Pull objects changed since a cursor","tags":["sync"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/leases/public-key":{"get":{"summary":"Public key for verifying offline entitlement leases","tags":["sync"],"parameters":[],"security":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/leases":{"post":{"summary":"Issue a signed, expiring offline entitlement lease","tags":["sync"],"parameters":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/audit":{"get":{"summary":"Audit events (org admin)","tags":["audit"],"parameters":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/audit/verify":{"get":{"summary":"Verify audit hash chain (org admin)","tags":["audit"],"parameters":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/openapi.json":{"get":{"summary":"This document","tags":["ops"],"parameters":[],"security":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/products/electrical/info":{"get":{"summary":"Product info and maturity","tags":["electrical"],"parameters":[],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/products/electrical/projects/{projectId}/models/{objectId}/drc":{"get":{"summary":"Design-rule check","tags":["electrical"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"objectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/products/electrical/projects/{projectId}/models/{objectId}/reports/{kind}":{"get":{"summary":"Wire list, cut list, BOM or test plan","tags":["electrical"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"objectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"kind","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/products/electrical/projects/{projectId}/test-records/{recordId}/evaluation":{"get":{"summary":"Evaluate a test record against its pinned plan","tags":["electrical"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"recordId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/products/electrical/projects/{projectId}/models/{objectId}/diagram.svg":{"get":{"summary":"Wiring diagram (SVG) generated from the model","tags":["electrical"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"objectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/products/electrical/projects/{projectId}/models/{objectId}/sheet.svg":{"get":{"summary":"Drafted schematic sheet (ISO size, zones, title block) generated from the model","tags":["electrical"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"objectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/products/electrical/projects/{projectId}/models/{objectId}/ladder.svg":{"get":{"summary":"Ladder diagram (SVG): series paths of symbol devices between two named rail nets","tags":["electrical"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"objectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/products/electrical/projects/{projectId}/models/{objectId}/nailboard.svg":{"get":{"summary":"Nail-board drawing (SVG, to scale) from the harness topology","tags":["electrical"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"objectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/products/electrical/projects/{projectId}/models/{objectId}/wire-selection":{"get":{"summary":"Select wires against a user-supplied wire library","tags":["electrical"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"objectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/products/electrical/projects/{projectId}/models/{objectId}/panel.svg":{"get":{"summary":"Panel layout front view (SVG, to scale)","tags":["electrical"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"objectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/products/electrical/projects/{projectId}/models/{objectId}/impact":{"get":{"summary":"Change impact between two revisions","tags":["electrical"],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"objectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{},"requestId":{"type":"string"}}}}}}}}