{"openapi":"3.1.0","info":{"title":"AIDC-AI.IO Engine & Agent API","version":"2026.06.05","description":"AI Data Center Automation Tool and infrastructure design engine for EngineSession-backed 3D graph generation and validation. Korean discovery phrase: AI 데이터센터 자동화 툴. The engine traces OPR, BOD, standards matrix, IT load/rack model, electrical topology, cooling topology, building/site fit, code/AHJ/fire/security validation, cost/procurement, commissioning, and operations evidence from the same graph. The public product presents one visual session backed by humanProjection and costSchedule read models, while AI agents read and mutate the same graph through API surfaces. `/api/engine/*` endpoints are same-origin; `/api/agent/*` wrappers add citation metadata and permissive CORS for cross-origin AI agent use.","contact":{"email":"contact@aidc-ai.io"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://aidc-ai.io","description":"Production"}],"tags":[{"name":"engine","description":"Internal engine endpoints (same-origin)"},{"name":"agent","description":"Cross-origin agent endpoints with citation"},{"name":"racks","description":"Public AI accelerator rack catalog"},{"name":"site-finder","description":"Site suitability gate and EngineSession handoff"},{"name":"access","description":"Scoped email verification for expert/procurement actions"}],"paths":{"/api/engine/design":{"post":{"tags":["engine"],"operationId":"engine_design","summary":"Generate an AI data center design basis","description":"Given OPR inputs such as IT load, rack density, GPU generation, and site area, returns a design-basis summary that can seed the shared 3D graph, humanProjection/costSchedule read models, and downstream validation artifacts. Rubin summaries snap racks to VR200 NVL72 8-rack planning zones and expose electrical PF/reserve assumptions, cooling liquid/air split, CDU planning values, WUE basis status, and a deterministic basisHash.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DesignRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DesignResponse"}}}},"400":{"$ref":"#/components/responses/BadInput"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/EngineError"},"503":{"$ref":"#/components/responses/NotConfigured"}},"security":[{},{"AIDCApiKey":[]}],"x-rate-limit":{"group":"engine","anonymousPerHour":30,"registeredPerHour":300,"partnerPerHour":0}}},"/api/engine/validate":{"post":{"tags":["engine"],"operationId":"engine_validate","summary":"Validate a data center design","description":"Checks a design against engineering rules (electrical, cooling, layout, safety, data). Returns severity-classified findings and RFI items.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateResponse"}}}},"400":{"$ref":"#/components/responses/BadInput"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/EngineError"},"503":{"$ref":"#/components/responses/NotConfigured"}},"security":[{},{"AIDCApiKey":[]}],"x-rate-limit":{"group":"engine","anonymousPerHour":30,"registeredPerHour":300,"partnerPerHour":0}}},"/api/engine/layout":{"post":{"tags":["engine"],"operationId":"engine_layout","summary":"Generate rackPlan and site layout","description":"Produces a rackPlan/site projection with hall dimensions, row/column rack coordinates, and site blocks for the EngineSession graph.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LayoutRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LayoutResponse"}}}},"400":{"$ref":"#/components/responses/BadInput"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/EngineError"},"503":{"$ref":"#/components/responses/NotConfigured"}},"security":[{},{"AIDCApiKey":[]}],"x-rate-limit":{"group":"engine","anonymousPerHour":30,"registeredPerHour":300,"partnerPerHour":0}}},"/api/agent/design":{"post":{"tags":["agent"],"operationId":"agent_design","summary":"Generate an AI data center design basis","description":"Given OPR inputs such as IT load, rack density, GPU generation, and site area, returns a design-basis summary that can seed the shared 3D graph, humanProjection/costSchedule read models, and downstream validation artifacts. Rubin summaries snap racks to VR200 NVL72 8-rack planning zones and expose electrical PF/reserve assumptions, cooling liquid/air split, CDU planning values, WUE basis status, and a deterministic basisHash.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DesignRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DesignResponseAgent"}}}},"400":{"$ref":"#/components/responses/BadInput"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/EngineError"},"503":{"$ref":"#/components/responses/NotConfigured"}},"security":[{},{"AIDCApiKey":[]}],"x-rate-limit":{"group":"agent","anonymousPerHour":10,"registeredPerHour":100,"partnerPerHour":1000}}},"/api/agent/validate":{"post":{"tags":["agent"],"operationId":"agent_validate","summary":"Validate a data center design","description":"Checks a design against engineering rules (electrical, cooling, layout, safety, data). Returns severity-classified findings and RFI items.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateResponseAgent"}}}},"400":{"$ref":"#/components/responses/BadInput"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/EngineError"},"503":{"$ref":"#/components/responses/NotConfigured"}},"security":[{},{"AIDCApiKey":[]}],"x-rate-limit":{"group":"agent","anonymousPerHour":10,"registeredPerHour":100,"partnerPerHour":1000}}},"/api/agent/layout":{"post":{"tags":["agent"],"operationId":"agent_layout","summary":"Generate rackPlan and site layout","description":"Produces a rackPlan/site projection with hall dimensions, row/column rack coordinates, and site blocks for the EngineSession graph.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LayoutRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LayoutResponseAgent"}}}},"400":{"$ref":"#/components/responses/BadInput"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/EngineError"},"503":{"$ref":"#/components/responses/NotConfigured"}},"security":[{},{"AIDCApiKey":[]}],"x-rate-limit":{"group":"agent","anonymousPerHour":10,"registeredPerHour":100,"partnerPerHour":1000}}},"/api/engine/cfd":{"post":{"tags":["engine"],"operationId":"engine_cfd","summary":"Bridge EngineSession graph to external CFD","description":"Builds an OpenFOAM-style CFD case package from the EngineSession/rackPlan graph, optionally submits it to the configured AIDC_CFD_SOLVER_URL external solver, and ingests aidc_openfoam_result_manifest.json back into the mechanical validation rows. This endpoint does not claim CFD pass/fail until a structured external result manifest is attached.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CfdRequest"}}}},"responses":{"200":{"description":"CFD case package, submit status, or attached result evaluation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CfdResponse"}}}},"400":{"$ref":"#/components/responses/BadInput"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/EngineError"},"503":{"$ref":"#/components/responses/NotConfigured"}},"security":[{},{"AIDCApiKey":[]}],"x-rate-limit":{"group":"engine","anonymousPerHour":30,"registeredPerHour":300,"partnerPerHour":0}}},"/api/racks":{"get":{"tags":["racks"],"operationId":"racks_list","summary":"List normalized AI accelerator rack catalog entries","description":"Returns normalized public rack-library summaries for rack-scale systems, server platforms, and cloud-only accelerator systems.","responses":{"200":{"description":"Rack catalog list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RackListResponse"}}}},"429":{"$ref":"#/components/responses/RateLimited"}},"x-rate-limit":{"group":"data","anonymousPerHour":120}}},"/api/racks/{slug}":{"get":{"tags":["racks"],"operationId":"racks_get","summary":"Get one rack catalog entry","description":"Returns one normalized rack-library entry plus its raw YAML source object for provenance-aware tools.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"example":"gb300-nvl72"}],"responses":{"200":{"description":"Rack catalog detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RackDetailResponse"}}}},"404":{"description":"Rack slug not found","content":{"application/json":{"schema":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"string"}}}}}},"429":{"$ref":"#/components/responses/RateLimited"}},"x-rate-limit":{"group":"data","anonymousPerHour":120}}},"/api/site-finder/selection":{"post":{"tags":["site-finder"],"operationId":"site_finder_selection","summary":"Save a suitable Site Finder selection into an EngineSession","description":"Site Finder is the new-project suitability gate. Only `suitabilityStatus: suitable` or `conditional` can create an EngineSession. Missing, invalid, `unsuitable`, `non-suitable`, unknown, or conflicting top-level/selectedSite suitability values are rejected with 422 and `site_unsuitable`; accepted selections return a 3D Rack View handoff URL.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteFinderSelectionRequest"}}}},"responses":{"200":{"description":"EngineSession created or resumed from a suitable selection","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteFinderSelectionResponse"}}}},"400":{"$ref":"#/components/responses/BadInput"},"422":{"description":"Site suitability gate rejected the save","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteUnsuitableResponse"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/auth/email/request":{"post":{"tags":["access"],"operationId":"email_access_request","summary":"Request scoped email verification","description":"Requests company-domain email verification for expert_modify or vendor_procurement. The request route does not return usable scoped access; /api/auth/email/verify is the only route that sets the scoped HttpOnly access cookie.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailAccessRequest"}}}},"responses":{"200":{"description":"Verification token or delivery status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailAccessRequestResponse"}}}},"400":{"$ref":"#/components/responses/BadInput"}}}},"/api/auth/email/verify":{"get":{"tags":["access"],"operationId":"email_access_verify","summary":"Verify scoped email access","description":"Verifies a signed email verification token and sets a scoped access cookie for protected follow-up surfaces such as Vendor/Procurement.","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string"}},{"name":"scope","in":"query","required":false,"schema":{"$ref":"#/components/schemas/EmailAccessScope"}}],"responses":{"200":{"description":"Scoped email access verified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailAccessVerifyResponse"}}}},"401":{"description":"Invalid or expired token","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}},"post":{"tags":["access"],"operationId":"email_access_verify_post","summary":"Verify scoped email access by JSON body","description":"Consumes a signed email verification token to set the final HttpOnly access cookie, or accepts an existing valid HttpOnly aidc_email_access cookie for the requested scope. Body-supplied access tokens are not accepted.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailAccessVerifyRequest"}}}},"responses":{"200":{"description":"Scoped email access verified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailAccessVerifyResponse"}}}},"401":{"description":"Invalid or expired token","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}}},"components":{"securitySchemes":{"AIDCApiKey":{"type":"http","scheme":"bearer","bearerFormat":"aidc_live_<32 hex>","description":"No key required for anon tier. Optional Authorization: Bearer aidc_live_<32 hex> upgrades tier when configured."}},"schemas":{"GpuGen":{"type":"string","enum":["hopper","blackwell","rubin"]},"Region":{"type":"string","enum":["metropolitan","regional"]},"Redundancy":{"type":"string","enum":["n","n_plus_1","2n"]},"CoolingMode":{"type":"string","enum":["air","hybrid","liquid"]},"SiteSuitabilityStatus":{"type":"string","enum":["suitable","conditional","unsuitable","non-suitable","unknown"]},"SaveableSiteSuitabilityStatus":{"type":"string","enum":["suitable","conditional"]},"EmailAccessScope":{"type":"string","enum":["expert_modify","vendor_procurement"]},"SiteFinderSelectionRequest":{"type":"object","required":["selectedSite"],"properties":{"selectedSite":{"type":"object","description":"Selected candidate site, parcel geometry/evidence, and suitability summary.","additionalProperties":true},"suitabilityStatus":{"$ref":"#/components/schemas/SaveableSiteSuitabilityStatus"},"suitabilityReasons":{"type":"array","items":{"type":"string"}},"rackIntake":{"type":"object","additionalProperties":true},"rackSummary":{"type":"object","additionalProperties":true},"diligenceLedger":{"type":"array","items":{}},"estimateFeed":{"type":"array","items":{}},"referenceCaseId":{"type":"string"}}},"AccessControl":{"type":"object","description":"Access requirements for human output surfaces. Manual Check/3D edits use sign-in access, Vendor/Procurement requires scoped email verification, and Cost/Schedule plus Spec/Validation remain readable outputs.","required":["expertModify","vendorProcurement","costSchedule","specValidation"],"properties":{"expertModify":{"type":"object","properties":{"requiresEmailVerification":{"type":"boolean","const":true},"scope":{"$ref":"#/components/schemas/EmailAccessScope"}}},"vendorProcurement":{"type":"object","properties":{"requiresEmailVerification":{"type":"boolean","const":true},"scope":{"$ref":"#/components/schemas/EmailAccessScope"}}},"costSchedule":{"type":"object","properties":{"requiresEmailVerification":{"type":"boolean","const":false}}},"specValidation":{"type":"object","properties":{"requiresEmailVerification":{"type":"boolean","const":false}}}}},"SiteFinderSelectionResponse":{"type":"object","required":["ok","data","requestId"],"properties":{"ok":{"type":"boolean","const":true},"data":{"type":"object","required":["sessionId","viewerUrl"],"properties":{"sessionId":{"type":"string","example":"aidc_sess_..."},"revisionId":{"type":"string"},"viewerUrl":{"type":"string","example":"/tools/3d_rack_viewer.html?session=aidc_sess_..."},"nextUrl":{"type":"string","example":"/tools/3d_rack_viewer.html?session=aidc_sess_..."},"designBasisUrl":{"type":"string","example":"/tools/system_configurator.html?session=aidc_sess_..."},"session":{"type":"object","additionalProperties":true}}},"requestId":{"type":"string"}}},"SiteUnsuitableResponse":{"type":"object","required":["ok","error","message","suitabilityStatus"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"string","const":"site_unsuitable"},"message":{"type":"string"},"suitabilityStatus":{"type":"string","description":"Rejected normalized suitability value. Missing values are returned as `unknown`.","enum":["unsuitable","non-suitable","unknown","invalid","suitable","conditional"]},"reasons":{"type":"array","items":{"type":"string"}}}},"EmailAccessRequest":{"type":"object","description":"Email must be a work email. If COMPANY_EMAIL_DOMAINS is set, only those domains are accepted; otherwise common personal email domains are blocked before a verification link is sent.","required":["email","scope"],"properties":{"email":{"type":"string","format":"email"},"scope":{"$ref":"#/components/schemas/EmailAccessScope"},"sessionId":{"type":"string"}}},"EmailAccessRequestResponse":{"type":"object","required":["ok","scope","verificationRequired","delivery"],"properties":{"ok":{"type":"boolean","const":true},"scope":{"$ref":"#/components/schemas/EmailAccessScope"},"sessionId":{"type":"string"},"verificationRequired":{"type":"boolean","const":true},"delivery":{"type":"string","enum":["email_sent","dev_verification_link"]},"provider":{"type":"string","enum":["resend"]},"devVerificationUrl":{"type":"string","description":"Development/test-only verification URL; not returned in production."}}},"EmailAccessVerifyRequest":{"type":"object","required":["scope"],"properties":{"token":{"type":"string","description":"Signed email verification token. Optional when the request already carries a valid HttpOnly aidc_email_access cookie. Body-supplied access tokens are not accepted."},"scope":{"$ref":"#/components/schemas/EmailAccessScope"},"sessionId":{"type":"string"}}},"EmailAccessVerifyResponse":{"type":"object","required":["ok","scope"],"properties":{"ok":{"type":"boolean","const":true},"scope":{"$ref":"#/components/schemas/EmailAccessScope"},"sessionId":{"type":"string"},"verifiedBy":{"type":"string","enum":["access_cookie","email_verification_cookie"],"description":"Shows whether access came from an existing HttpOnly cookie or a newly consumed email verification token that set the HttpOnly cookie."}}},"RackSummary":{"type":"object","required":["slug","displayName","manufacturer","model","vendor","generation","status","chassisUnit","modelingScope","commercialModel","dataQuality","confidence","lastVerified","powerKw","powerBasis","coolingTopology","acceleratorModel","acceleratorCount","hbmSpec","hbmTotalGb","fabricType","domainSize","hasBom","bomTotalUsd","evidenceCount"],"properties":{"slug":{"type":"string","example":"gb300-nvl72"},"displayName":{"type":"string","example":"NVIDIA GB300 NVL72"},"manufacturer":{"type":"string","example":"NVIDIA"},"model":{"type":"string","example":"GB300 NVL72"},"vendor":{"type":"string","example":"nvidia"},"generation":{"type":"string","example":"blackwell_ultra"},"status":{"type":"string","example":"public_reference"},"chassisUnit":{"type":"string","description":"Normalized catalog unit such as rack_scale, server, or cloud_pod."},"modelingScope":{"type":"string"},"commercialModel":{"type":"string"},"dataQuality":{"type":"string"},"confidence":{"type":["string","null"]},"lastVerified":{"type":"string"},"powerKw":{"type":["number","null"]},"powerBasis":{"type":["string","null"]},"coolingTopology":{"type":["string","null"]},"acceleratorModel":{"type":["string","null"]},"acceleratorCount":{"type":["number","null"]},"hbmSpec":{"type":["string","null"]},"hbmTotalGb":{"type":["number","null"]},"fabricType":{"type":["string","null"]},"domainSize":{"type":["number","null"]},"hasBom":{"type":"boolean"},"bomTotalUsd":{"type":["number","null"]},"evidenceCount":{"type":"integer"}}},"RackListResponse":{"type":"object","required":["ok","generatedAt","count","racks"],"properties":{"ok":{"type":"boolean","const":true},"generatedAt":{"type":"string","format":"date-time"},"count":{"type":"integer"},"racks":{"type":"array","items":{"$ref":"#/components/schemas/RackSummary"}}}},"RackDetailResponse":{"type":"object","required":["ok","generatedAt","rack","raw"],"properties":{"ok":{"type":"boolean","const":true},"generatedAt":{"type":"string","format":"date-time"},"rack":{"$ref":"#/components/schemas/RackSummary"},"raw":{"type":"object","description":"Raw parsed rack-library YAML object.","additionalProperties":true}}},"DesignRequest":{"type":"object","required":["itLoadMw","rackDensityKw","gpuGen","siteAreaSqm","region"],"properties":{"itLoadMw":{"type":"number","exclusiveMinimum":0,"maximum":1000,"description":"IT load in MW (0 < x ≤ 1000)"},"rackDensityKw":{"type":"number","exclusiveMinimum":0,"maximum":500,"description":"Per-rack power in kW (0 < x ≤ 500)"},"gpuGen":{"$ref":"#/components/schemas/GpuGen"},"siteAreaSqm":{"type":"number","exclusiveMinimum":0,"maximum":1000000,"description":"Site area in m² (0 < x ≤ 1,000,000)"},"region":{"$ref":"#/components/schemas/Region"},"parcels":{"type":"array","description":"Optional GeoJSON Polygon / MultiPolygon features.","items":{"type":"object"}},"options":{"type":"object","properties":{"redundancy":{"$ref":"#/components/schemas/Redundancy"},"coolingMode":{"$ref":"#/components/schemas/CoolingMode"},"pueTarget":{"type":"number","minimum":1,"maximum":2.5}}}}},"DesignSummary":{"type":"object","required":["rackCount","pueDesign","mvaTotal"],"properties":{"rackCount":{"type":"integer","description":"Rack count after deployment-unit snapping. For Rubin this is snapped to 8-rack VR200 NVL72 planning zones."},"unsnappedRackCount":{"type":"integer","description":"Raw ceil(IT kW / effective rack kW) count before deployment-unit snapping."},"requestedRackDensityKw":{"type":"number"},"effectiveRackDensityKw":{"type":"number"},"deploymentUnitKind":{"type":"string","example":"vr200_nvl72_8_rack_planning_zone"},"deploymentUnitCount":{"type":"integer"},"racksPerUnit":{"type":"integer"},"gpusPerUnit":{"type":"integer"},"pueDesign":{"type":"number"},"pueAnnualBasis":{"type":"number"},"mvaTotal":{"type":"number","description":"Facility apparent-power planning total: IT MW × PUE × coincident load × redundancy factor × design reserve / power factor."},"facilityDemandMw":{"type":"number"},"powerFactor":{"type":"number"},"redundancyFactor":{"type":"number"},"designReserveFactor":{"type":"number"},"coincidentLoadFactor":{"type":"number"},"transformerTargetLoadingPct":{"type":"number"},"totalCostKrw":{"type":"number"},"totalMonths":{"type":"number"},"coolingLoadMw":{"type":"number","description":"IT heat load to reject before cooling-capacity reserve."},"coolingCapacityMw":{"type":"number","description":"Planning cooling capacity after the selected cooling-mode reserve factor."},"liquidCoolingLoadMw":{"type":"number"},"airCoolingLoadMw":{"type":"number"},"liquidHeatRejectionPct":{"type":"number"},"airHeatRejectionPct":{"type":"number"},"cduUnitMw":{"type":"number"},"cduCount":{"type":"integer"},"cduInstalledMw":{"type":"number"},"cduRedundancy":{"type":"string"},"secondaryLoopDeltaTC":{"type":"number"},"cduApproachTempC":{"type":"number"},"tcsSupplyTempC":{"type":"number"},"wueBasisStatus":{"type":"string","description":"WUE is climate/water-strategy dependent in public preview and remains an RFI-backed basis status unless project evidence supplies it."},"basisHash":{"type":"string","description":"Deterministic hash of sizing inputs and public planning assumptions."},"hallCount":{"type":"integer"}}},"HumanProjection":{"type":"object","description":"Human-track read model derived from the same EngineSession graph. Use for session cards, 3D review links, validation/RFI status, procurement readiness, commissioning, and handover status.","required":["status","track","cards","actions","alerts"],"properties":{"status":{"type":"string","example":"requires_validation"},"track":{"type":"object","required":["human","agent"],"properties":{"human":{"type":"string","example":"visual_session"},"agent":{"type":"string","example":"full_graph_api"}}},"cards":{"type":"array","items":{"type":"object","required":["id","title","value","status"],"properties":{"id":{"type":"string","example":"opr"},"title":{"type":"string","example":"OPR"},"value":{"type":"string","example":"50 MW IT"},"status":{"type":"string","example":"requires_validation"},"href":{"type":"string"}}}},"actions":{"type":"array","items":{"type":"object","required":["id","label","href"],"properties":{"id":{"type":"string","example":"open_3d"},"label":{"type":"string","example":"Open 3D review"},"href":{"type":"string","example":"/tools/3d_rack_viewer.html"}}}},"alerts":{"type":"array","items":{"type":"object","required":["id","message"],"properties":{"id":{"type":"string","example":"downstream_revalidation"},"message":{"type":"string"},"severity":{"type":"string","example":"warn"}}}}}},"CostSchedule":{"type":"object","description":"Human-track cost, schedule, and procurement readiness read model derived from BOM, estimate, RFIs, evidence, and commissioning stage gates.","required":["status","currency","totalKrw","scheduleRows","procurementRows","criticalPathRows"],"properties":{"status":{"type":"string","example":"generated_preliminary"},"currency":{"type":"string","example":"KRW"},"totalKrw":{"type":"number"},"contingencyKrw":{"type":"number"},"totalMonths":{"type":"number"},"estimateBuckets":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"krwPerKw":{"type":"number"},"amountKrw":{"type":"number"},"status":{"type":"string"}}}},"scheduleRows":{"type":"array","items":{"type":"object","required":["id","label","months","owner","status"],"properties":{"id":{"type":"string","example":"long_lead_procurement"},"label":{"type":"string"},"months":{"type":"number"},"owner":{"type":"string","example":"Vendor/Procurement"},"status":{"type":"string","example":"rfi_required"}}}},"procurementRows":{"type":"array","items":{"type":"object","required":["id","item","quantity"],"properties":{"id":{"type":"string"},"item":{"type":"string"},"category":{"type":"string"},"quantity":{"type":"number"},"source":{"type":"string"},"procurementReady":{"type":"boolean"},"rfiRequired":{"type":"boolean"},"evidenceStatus":{"type":"string"},"leadMonths":{"type":"number"}}}},"criticalPathRows":{"type":"array","items":{"type":"object","additionalProperties":true}},"stageGateRefs":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"DerivedArtifacts":{"type":"object","description":"Selected EngineSession-derived artifacts. Human surfaces read humanProjection and costSchedule; AI-agent clients may request or follow graph/API links for the fuller rackPlan, facilityFlowModel, node/edge schemas, SLD/Sankey/pandapower, BOM, estimate, RFIs, and evidence refs.","properties":{"humanProjection":{"$ref":"#/components/schemas/HumanProjection"},"costSchedule":{"$ref":"#/components/schemas/CostSchedule"},"accessControl":{"$ref":"#/components/schemas/AccessControl"}},"additionalProperties":true},"DesignResponse":{"type":"object","required":["ok","generatedAt","summary","warnings","engineVersion","requestId"],"properties":{"ok":{"type":"boolean","const":true},"generatedAt":{"type":"string","format":"date-time"},"summary":{"$ref":"#/components/schemas/DesignSummary"},"derivedArtifacts":{"$ref":"#/components/schemas/DerivedArtifacts"},"warnings":{"type":"array","items":{"type":"string"}},"engineVersion":{"type":"string"},"requestId":{"type":"string"}}},"DesignResponseAgent":{"allOf":[{"$ref":"#/components/schemas/DesignResponse"},{"type":"object","required":["_agent"],"properties":{"_agent":{"type":"object","description":"Metadata attached to /api/agent/* responses. Lets the calling agent cite the source and discover related endpoints.","required":["citation","api","usage"],"properties":{"citation":{"type":"object","required":["provider","url","description"],"properties":{"provider":{"type":"string"},"url":{"type":"string","format":"uri"},"description":{"type":"string"}}},"api":{"type":"object","required":["openapi","plugin","docs"],"properties":{"openapi":{"type":"string","format":"uri"},"plugin":{"type":"string","format":"uri"},"docs":{"type":"string","format":"uri"}}},"usage":{"type":"object","required":["rateLimit","auth","contact"],"properties":{"rateLimit":{"type":"string"},"auth":{"type":"string"},"contact":{"type":"string"}}}}}}}]},"ValidateRequest":{"type":"object","description":"Either designSummary OR rawInput must be provided. Engine decides which to use.","properties":{"designSummary":{"$ref":"#/components/schemas/DesignSummary"},"rawInput":{"$ref":"#/components/schemas/DesignRequest"}}},"ValidationFinding":{"type":"object","required":["severity","family","message"],"properties":{"severity":{"type":"string","enum":["blocking","warn","info"]},"family":{"type":"string","enum":["electrical","cooling","layout","safety","data"]},"message":{"type":"string"},"publicRuleId":{"type":"string"}}},"RfiItem":{"type":"object","required":["id","topic","owner","status"],"properties":{"id":{"type":"string"},"topic":{"type":"string"},"owner":{"type":"string","enum":["Vendor","Owner","Eng","Code"]},"status":{"type":"string","enum":["OPEN","VENDOR","OWNER","CLOSED"]}}},"ValidateResponse":{"type":"object","required":["ok","findings","rfis","engineVersion","requestId"],"properties":{"ok":{"type":"boolean","const":true},"findings":{"type":"array","items":{"$ref":"#/components/schemas/ValidationFinding"}},"rfis":{"type":"array","items":{"$ref":"#/components/schemas/RfiItem"}},"engineVersion":{"type":"string"},"requestId":{"type":"string"}}},"ValidateResponseAgent":{"allOf":[{"$ref":"#/components/schemas/ValidateResponse"},{"type":"object","required":["_agent"],"properties":{"_agent":{"type":"object","description":"Metadata attached to /api/agent/* responses. Lets the calling agent cite the source and discover related endpoints.","required":["citation","api","usage"],"properties":{"citation":{"type":"object","required":["provider","url","description"],"properties":{"provider":{"type":"string"},"url":{"type":"string","format":"uri"},"description":{"type":"string"}}},"api":{"type":"object","required":["openapi","plugin","docs"],"properties":{"openapi":{"type":"string","format":"uri"},"plugin":{"type":"string","format":"uri"},"docs":{"type":"string","format":"uri"}}},"usage":{"type":"object","required":["rateLimit","auth","contact"],"properties":{"rateLimit":{"type":"string"},"auth":{"type":"string"},"contact":{"type":"string"}}}}}}}]},"CfdRequest":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["prepare_case","submit_run","attach_result"]},"sessionId":{"type":"string","description":"EngineSession id. Preferred source because CFD must derive from the same 3D graph/rackPlan."},"rawInput":{"type":"object","additionalProperties":true,"description":"Fallback raw engine input when no EngineSession exists."},"caseName":{"type":"string"},"resultManifest":{"type":"object","additionalProperties":true,"description":"Structured aidc_openfoam_result_manifest.json for attach_result."},"companionManifests":{"type":"object","additionalProperties":{"type":"object","additionalProperties":true}},"attachments":{"type":"array","items":{"type":"object","additionalProperties":true}},"options":{"type":"object","properties":{"timeoutMs":{"type":"integer","minimum":1000,"maximum":120000},"includeCaseFiles":{"type":"boolean"}}}}},"CfdResponse":{"type":"object","required":["ok","action","status","generatedAt","engineVersion","requestId"],"properties":{"ok":{"type":"boolean","const":true},"action":{"type":"string","enum":["prepare_case","submit_run","attach_result"]},"status":{"type":"string","examples":["case_package_ready","solver_not_configured","submitted","result_attached_to_session"]},"generatedAt":{"type":"string","format":"date-time"},"casePackage":{"type":"object","additionalProperties":true,"description":"OpenFOAM-style case package or summary with files omitted, depending on options/action."},"casePackageSummary":{"type":"object","additionalProperties":true,"description":"Hash, scenario count, boundary counts, file list, and result evidence contract."},"externalDispatch":{"type":"object","additionalProperties":true,"description":"External solver submit status. If AIDC_CFD_SOLVER_URL is missing, status is solver_not_configured and no CFD pass/fail is claimed."},"resultEvaluation":{"type":"object","additionalProperties":true,"description":"Manifest-derived PASS/PENDING/REJECT evaluation."},"session":{"type":"object","additionalProperties":true},"sessionId":{"type":"string"},"revisionId":{"type":"string"},"engineVersion":{"type":"string"},"requestId":{"type":"string"}}},"LayoutRequest":{"type":"object","required":["design"],"properties":{"design":{"$ref":"#/components/schemas/DesignRequest"},"siteCentroid":{"type":"object","required":["lat","lng"],"properties":{"lat":{"type":"number"},"lng":{"type":"number"}}},"siteAreaSqm":{"type":"number","exclusiveMinimum":0}}},"RackBlock":{"type":"object","required":["xMm","yMm","kw"],"properties":{"xMm":{"type":"number"},"yMm":{"type":"number"},"kw":{"type":"number"}}},"SiteBlock":{"type":"object","required":["id","label","xPct","yPct","wPct","hPct"],"properties":{"id":{"type":"string"},"label":{"type":"string"},"xPct":{"type":"number"},"yPct":{"type":"number"},"wPct":{"type":"number"},"hPct":{"type":"number"},"fill":{"type":"string"}}},"LayoutResponse":{"type":"object","required":["ok","rackPlan","sitePlan","warnings","engineVersion","requestId"],"properties":{"ok":{"type":"boolean","const":true},"rackPlan":{"type":"object","required":["hallWidthMm","hallDepthMm","rows","cols","blocks"],"properties":{"hallWidthMm":{"type":"number"},"hallDepthMm":{"type":"number"},"rows":{"type":"integer"},"cols":{"type":"integer"},"blocks":{"type":"array","items":{"$ref":"#/components/schemas/RackBlock"}}}},"sitePlan":{"type":"object","required":["blocks"],"properties":{"blocks":{"type":"array","items":{"$ref":"#/components/schemas/SiteBlock"}}}},"warnings":{"type":"array","items":{"type":"string"}},"engineVersion":{"type":"string"},"requestId":{"type":"string"}}},"LayoutResponseAgent":{"allOf":[{"$ref":"#/components/schemas/LayoutResponse"},{"type":"object","required":["_agent"],"properties":{"_agent":{"type":"object","description":"Metadata attached to /api/agent/* responses. Lets the calling agent cite the source and discover related endpoints.","required":["citation","api","usage"],"properties":{"citation":{"type":"object","required":["provider","url","description"],"properties":{"provider":{"type":"string"},"url":{"type":"string","format":"uri"},"description":{"type":"string"}}},"api":{"type":"object","required":["openapi","plugin","docs"],"properties":{"openapi":{"type":"string","format":"uri"},"plugin":{"type":"string","format":"uri"},"docs":{"type":"string","format":"uri"}}},"usage":{"type":"object","required":["rateLimit","auth","contact"],"properties":{"rateLimit":{"type":"string"},"auth":{"type":"string"},"contact":{"type":"string"}}}}}}}]},"ErrorResponse":{"type":"object","required":["ok","error","requestId"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["BAD_INPUT","RATE_LIMITED","ENGINE_NOT_CONFIGURED","ENGINE_ERROR"]},"message":{"type":"string"}}},"requestId":{"type":"string"}}}},"responses":{"BadInput":{"description":"Invalid request body (Zod validation failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimited":{"description":"Too many requests. Per-hour limits per (tier × route group). Anonymous (per IP): agent=10, engine=30, vworld=600, data=120, contact=5, estimate=5. Registered (Bearer key): 10x. See /llms.txt §Rate limits or /.well-known/api-catalog.","headers":{"Retry-After":{"schema":{"type":"integer"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"}},"X-RateLimit-Tier":{"schema":{"type":"string","enum":["anon","registered","partner"]}},"X-RateLimit-Group":{"schema":{"type":"string","enum":["agent","engine","vworld","data","contact","estimate","other"]}}},"content":{"application/json":{"schema":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","const":"rate_limit_exceeded"},"message":{"type":"string"},"docs":{"type":"string","format":"uri"},"sign_up":{"type":"string","format":"uri"}}}}}},"EngineError":{"description":"Internal engine error — reference requestId for support","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotConfigured":{"description":"Engine module not yet wired (stub mode — Codex update pending)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}