Private pilot API
Convert. Propose. Verify.
Your AI and model history, connected to a bounded compiler.
API base URL: https://api.houseir.unum11.com. Access uses individually issued customer keys. The deployed compiler passed scoped synthetic HTTPS operational checks and a real-house conversion/metadata-edit workflow. Access and supported scope are agreed individually. The landing page does not accept model uploads.
Health and capability discovery still report release_ready: false for broad release status. Scoped pilot evidence and each job’s verification report are separate; a configured release label does not change that flag.
Authentication and discovery
Send your customer-specific HouseIR key in Authorization: Bearer … on discovery, job, status and artifact requests. Your application supplies its own AI; no AI-provider key is required by HouseIR. Keep the HouseIR key on your trusted backend, never in browser code. Set HOUSEIR_API_URL to https://api.houseir.unum11.com and supply HOUSEIR_API_KEY through your secret configuration.
GET /v1/capabilities
GET /v1/operations/schema
GET /v1/workflows
Read the installed operation schema and restrictions before constructing edits. Twenty structured operations cover supported object changes, bounded walls/openings, circuit metadata, new device connections and straight route sections. They do not make every imported representation editable. Circuit ratings are supplied metadata, not electrical sizing calculations.
POST /v1/jobs
Authorization: Bearer YOUR_HOUSEIR_KEY
Content-Type: application/json
Idempotency-Key: saved-request-001Request fields are operation, ifc_base64, bir, residual_base64, editing_profile, base_bir_sha256 and operations, as applicable below. A successful admission returns HTTP 202 with a job record, including its id and status. Admission is not successful compilation.
Persist an optional retry key before submission. Repeating identical content with the same customer-scoped key returns the same job; different content returns HTTP 409. A retry does not extend artifact expiry. Use a new key for each intentional new operation.
1. Convert IFC into BIR
{
"operation": "convert",
"ifc_base64": "BASE64_ENCODED_IFC_BYTES",
"editing_profile": "individual"
}Use individual for named-object editing; the default compact profile may group objects into bulk rows. This field applies only to conversion. Successful conversion provides model.bir, residual.hir and report.json. Keep the exact BIR/residual pair together. The signed residual preserves source information and is bound to your customer identity; another conversion of the same IFC may produce a different pair.
Conversion checks exact text and semantic round trips and supported lifted geometry. Opaque statements retain source data but are not certified as editable geometry. Unsupported verification can cause the whole job to fail.
Individual-profile protection
Individual conversion preserves unsupported or unproved objects while exposing only verified editable geometry. The compact profile retains its previous behavior.
Source eligibility and one bounded candidate-classification pass separate supported editable geometry from protected Opaque content. Unsupported representations, nonphysical annotations and objects whose geometric proof cannot be established remain in the exact original residual. Proof-budget exhaustion means proof was not established; it is never counted as a pass. After at most one rebuild, every remaining editable product must pass the final strict less-than-1-mm gate. Exact text and unchanged whole-model semantic replay remain required.
The conversion report identifies protected products and reasons in source_eligibility.protected_products, and verified lifted IFC GlobalIds in editable_geometry_product_ids. source_eligibility.fully_editable remains false. These lists do not authorize every operation on every listed object; use actual BIR object IDs and the installed operation schema.
The authenticated residual policy applies to raw compilation and structured edits. Direct changes or removal of protected objects, and indirect changes affecting their geometry, placement, types, materials, properties or connections, are rejected. Other edits must preserve that protected context. One narrow exception permits declared name/number label changes on an independently editable room referenced by IfcRelSpaceBoundary; protected geometry, GUIDs, placement and other dependencies remain strict, and the report records the allowed label attributes. Exact unchanged replay with the original residual remains supported. No new operation names or full-model editability claim are added.
Real-house HTTPS checkpoint: the deployed API converted the FZK architectural model with 60 verified editable products and 63 protected products, including 14 annotations. It renamed Buero to Home office, retaining room number 2. Independent inspection restored only the requested label in memory and compared all 44,249 IFC entities; normalized whole-model semantics matched exactly, preserving geometry, relationships and rooted IDs. The edit introduced zero new schema problems.
Recorded server processing time was 147.874 seconds for conversion and 25.235 seconds for the edit. This is one architectural metadata workflow, not a geometric remodel, MEP edit, capacity benchmark or engineering approval. Earlier refused attempts remain recorded. Source model: Institute for Automation and Applied Informatics (IAI) / Karlsruhe Institute of Technology (KIT), CC-BY-4.0.
The full local release passed with unchanged source: 899 BIR tests with one optional CAD skip; 264 house tests with no skips; scripts (27), Python SDK (32), TypeScript SDK (14), viewer (5), semantic scenarios (14) and container smoke cases (7) passed. The original frozen 90 AI proposals replayed 90/90 for regression; they are not new AI attempts. Separate synthetic HTTPS checks on the deployed image passed authentication/isolation, retries, limits, interrupted-worker recovery and accelerated retention. The real-house metadata workflow above passed separately; customer-specific model and workflow acceptance remains required.
2. Propose a structured edit
{
"operation": "edit",
"bir": "EXACT_CURRENT_BIR_TEXT",
"base_bir_sha256": "SHA256_OF_EXACT_UTF8_BIR_BYTES",
"residual_base64": "BASE64_ENCODED_ORIGINAL_RESIDUAL_HIR_BYTES",
"operations": [
{"operation": "rename_object", "object_id": "ACTUAL_BIR_OBJECT_ID", "label": "Reading light"}
]
}Replace the placeholders with actual retained bytes and an object ID from your BIR. The hash must be 64 lowercase hexadecimal characters; preserve line endings. An edit accepts 1–100 operations and produces model.bir, model.ifc and report.json only after verification. Unsupported geometry, dependencies or failed preservation checks reject the proposal.
The hash checks the submitted base text. It does not compare against a server-managed project head. Review and accept the result in your own revision store, enforcing your own concurrent-edit checks. For the next edit, send the latest accepted BIR and hash with the original sealed residual.
3. Optional language check and explicit compilation
{
"operation": "check",
"bir": "YOUR_BIR_TEXT"
}Read valid and problems in the resulting report.json. This checks language and references only. It does not certify IFC validity, geometry, engineering design or the success of a later compile.
If your application edits BIR text directly, compile it with the original residual:
{
"operation": "compile",
"bir": "YOUR_EDITED_BIR_TEXT",
"residual_base64": "BASE64_ENCODED_RESIDUAL_HIR_BYTES"
}Successful compilation provides model.ifc and report.json. The original signed residual is required. The supported edit scope is agreed during the pilot; language expressiveness does not imply every operation is hosted and verified.
new is present in the development interface but certified hosted fresh-model generation is not released. Do not integrate it as an available operation.
Poll and download
GET /v1/jobs/{id}
GET /v1/jobs/{id}/artifacts/report.json
GET /v1/jobs/{id}/artifacts/model.bir
GET /v1/jobs/{id}/artifacts/residual.hir
GET /v1/jobs/{id}/artifacts/model.ifc
GET /v1/jobs/{id}/artifacts/diagnostic.jsonJob IDs are 32 lowercase hexadecimal characters. Poll the returned record: accepted and running are pending; verified means a convert, edit or compile completed its scoped checks; checked means a language check completed (read its valid value). failed, unsupported, verification_failed, timed_out and expired require handling. Download only the names listed in that record's artifacts. Failed jobs expose diagnostics when available, not a successful IFC artifact.
Compare downloaded artifact SHA256 hashes with artifact_sha256 in the authenticated report. Compile/edit reports also bind residual_sha256 to the exact original sealed residual. Retain reports with your artifacts; never promote mismatched or incomplete downloads.
curl --fail-with-body "$HOUSEIR_API_URL/v1/jobs/$JOB_ID" \
-H "Authorization: Bearer $HOUSEIR_API_KEY"
curl --fail-with-body \
"$HOUSEIR_API_URL/v1/jobs/$JOB_ID/artifacts/report.json" \
-H "Authorization: Bearer $HOUSEIR_API_KEY" \
--output report.json
Limits and retention
| Boundary | Current default |
|---|---|
| Decoded IFC input | 40 MiB (41,943,040 bytes) |
| BIR UTF-8 input | 10 MiB (10,485,760 bytes) |
| Total JSON request | 150 MiB; individual input limits still apply |
| Execution window | Up to 30 minutes from admission |
| Model-data retention | One hour from admission; download before expiry |
| Concurrency | One admitted compiler job per instance; busy requests receive 429 |
Content-free usage metadata may be retained for 90 days. These are processing limits, not promises that every model under the limit succeeds. Geometry complexity and representation support matter.
| HTTP response | Meaning |
|---|---|
| 401 | Missing, invalid or revoked API key |
| 404 | Unknown job or unavailable artifact; other customers' jobs are not exposed |
| 409 | Retry key reused with different request content |
| 410 | Requested job artifacts have expired |
| 413 | Total request exceeds its limit |
| 422 | Invalid fields, encoding, operation inputs or input size |
| 429 | Compiler busy; honor Retry-After: 10 |
HouseIR is a transient compiler, not your model archive. Model-bearing artifacts expire one hour after admission, including while you are reviewing them. Save the original matched BIR/residual, verified revisions and reports into customer-owned storage before expiry. The customer controls the authoritative model, revision acceptance and rollback.
MCP access
This rollout is API-first. The local houseir-api-mcp stdio adapter connects to the same API using HOUSEIR_API_URL and HOUSEIR_API_KEY; your AI client launches it locally. A separate Streamable HTTP implementation has local integration tests, but public remote MCP identity-provider/login setup is deferred. The API address is not an OAuth MCP endpoint.
What the report proves
The report records the operation, provenance and performed checks. Where supported, geometry verification requires a bound strictly below 1 mm, including applicable approximation allowances. Compile checks untouched semantic preservation and new schema problems within the reported validation scope.
Whole-model attribute/schema checks do not constitute full-model EXPRESS or normative validation. Edits also check a bounded touched-product EXPRESS subset. Supported architecture and MEP primitives have independent IFC intent checks. Those checks do not constitute a complete building-design oracle or certify every service concealed in an imported model.
HouseIR does not certify engineering safety, building-code compliance, constructability or complete design intent. A pilot must include independent review in the partner's target software. Treat omitted or refused checks as unsupported, never as passed.
IFC interoperability
IFC is the pilot exchange format. Verify import behavior in the software and version you intend to support. IFC import into a proprietary authoring tool is different from creating fully editable native elements. No open-source IFC-to-RVT conversion, native RVT round trip or universal format conversion is promised by this API.
Inspect a scripted MEP edit
Download the synthetic MEP demo ZIP to inspect the before/after artifacts and reports. The script extends a straight pipe from 1,000 to 1,400 mm and checks preservation of its GlobalId, ports, system and neighboring element. This is a scripted compiler evaluation, not an AI-generated edit or proof of general MEP coverage. Bent-fitting editing is explicitly refused.
Start a pilot
Tell us your target software, representative model sizes and requested edits. We will agree supported operations, independent review and acceptance criteria before a proposed $500 scoped pilot begins.
Contract updated October 12, 2026. The current local release passed: 899 BIR and 264 house tests, with one optional CAD skip; SDK, scripts, viewer and semantic stages passed; seven container smoke cases passed. Three fresh AI sessions scored 90/90 proposals on 30 synthetic tasks (81 writes, nine correct refusals), with zero accepted task-contract violations. The deployed image passed bounded synthetic hosted checks; these results do not establish a customer-model success rate, sustained capacity or engineering approval. Broader corpus repairs and external review remain open.