The Design API lets an authorized tool create, read and replace the Building Design part of your private cloud projects. The same JSON can be imported into the visual editor. This API does not control the live browser, containers, furniture studios, accounts or billing.
Cloud project limits are shared with the editor: 5 free projects per registered account, or 25 total with the $9.99 USD/month Plus plan. Existing projects remain editable at the limit. PayPal checkout availability is shown in My Projects.
Download the photo-to-design AI kit: a prompt, the complete schema and a valid example in one attachment, available in English and Spanish. Add known dimensions, then give the kit and photos to your preferred AI. Import the resulting design JSON and review it before replacing your building. This file-based workflow needs no account or API key.
Sign in → My projects → API access for design tools. Choose read-only or edit access, all projects or one project, and an expiry (1–90 days). Confirm your account password and copy the key shown once. An edit key scoped to all projects can also create projects. You can revoke it at any time. Account recovery invalidates existing keys.
Keep the key in your tool's secret store or a local environment variable, not in prompts, screenshots, source control or URLs. No server/SSH access is needed. No Codex or third-party integration is installed automatically; any authorized tool capable of HTTP can use this contract.
Select an element, choose Material and Texture in its properties, optionally set Texture repeat (m) and Color override, then Apply element. Clear Color override to see the material’s default color. For roofs choose Roof shape, bottom elevation and height. Undo restores the prior finish. The textured coastal example is an approximate exterior study with an orthogonal footprint, estimated dimensions and simplified ornament. Detailed facade meshes are batched by material while retaining element selection. Daylight, grid visibility and elevation cameras are available in 3D. Shadows remain enabled for detailed models.
Windows and doors accept an optional openingStyle object. Arched openings cut real curved holes in their host walls; frames and surrounds are editable geometry. Without this object, legacy rendering is preserved.
{"shape":"arch","columns":2,"rows":3,"frameWidth":0.045,"frameColor":"#666961","trimWidth":0.10,"trimDepth":0.07,"trimColor":"#E4E0D4"}All eight fields are required when openingStyle is present. Shape: rectangular or arch. Columns 1–6, rows 1–8; frameWidth 0.015–0.15 m; trimWidth 0–0.5 m; trimDepth 0.01–0.3 m. Colors use #RRGGBB. Arch rise is min(width/2, height×0.45). Pane dividers follow the curved profile. Decorative surrounds may extend outside the wall opening; allow spacing for them. In the editor, select a wall and expand Repeat windows along this wall. The centered pattern adds independently editable windows and rejects overlaps. Undo restores the previous wall. Duplicate a level to repeat vertically.
Use Open coastal landmark in Building Design or Project files, review the preview, then replace the current design. The example has 19 modeling levels, detailed frames, arched ground-floor openings, pilasters, cornices, copper roofs and an octagonal spire. Its dimensions and orthogonal footprint remain estimates from photos, not a surveyed reproduction.
Node.js 18+; no packages required. Set BUILDING3D_API_KEY privately in the process environment, then:
node building3d-client.mjs validate simple-house.design.json node building3d-client.mjs create simple-house.design.json house-request-0001 node building3d-client.mjs list node building3d-client.mjs get PROJECT_ID node building3d-client.mjs update PROJECT_ID CURRENT_REVISION edited-house.design.json
Create returns a project ID and revision. Retry an uncertain create with the same request ID and identical design: it returns the original project, not a duplicate. Use a new request ID for a new design. Request IDs are retained for 30 days. Read before updating; a 409 means another writer changed the project. Reconcile changes before retrying.
Base: https://building3d.app/api/design. Every request needs Authorization: Bearer YOUR_KEY. POST and PUT use Content-Type: application/json. Session cookies do not authenticate API requests.
| Request | Action | Permission |
|---|---|---|
| GET /api/design | List accessible projects | read |
| GET /api/design?id=ID | Read design + revision | read |
| POST /api/design?action=validate | Validate + return canonical design, metrics and warnings | Any valid key |
| POST /api/design | Create private project; Idempotency-Key header required | create |
| PUT /api/design?id=ID | Replace building; other studios preserved | write |
POST body: { "design": { ... } }
PUT body: { "revision": 3, "design": { ... } }
GET result: { "project": { "id": "...", "name": "...", "revision": 3,
"updated": 1791740000, "design": { ... } } }
Error: { "error": { "code": "INVALID_DESIGN", "message": "...",
"issues": [{ "path": "/elements/0", "message": "..." }] } }
API updates do not silently replace a design open in a browser. In My projects, Refresh list and reopen the project. If the browser has unsaved changes, save a separate copy or reconcile them first. Both browser and API saves enforce revisions.
format: "building3d.design", version: 1, metres, levels ordered bottom to top. Level elevation = baseElevation + previous level heights.Walls accept optional curtainWall: {"shape":"ellipse","bays":64,"rows":1}. Use shape "flat" for a planar glazed facade. Ellipse width/depth specify outer diameters, with hollow geometry; bays (1–80) and rows (1–8) control the glazing grid. Hosted openings are not supported on curtain walls. Use separate standard entrance walls. Export and reimport preserve these settings.
Limits: 1.5 MB/design, 60 levels, 150 elements/level, 3000 elements total, 30 saved projects/account, 4 MB/workspace, 60 API requests/minute/account. Site 8–100 m; floor-to-floor height 2.4–6 m; name up to 120 UTF-8 bytes. Unknown fields, unsupported versions and invalid geometry are rejected; never silently discarded. Optional texture: none, concrete, stucco, stone, brick, wood, standing-seam or tiles. Omit it to use the material default. textureScale is the tile repeat size in meters (0.1–20); changing dimensions preserves texture density. Roof dimensions.height is the total rise above position.y. Gable/hip ridges run along local X; use rotation.y to turn them. Pyramid has a centered apex. Octagonal is an eight-sided spire inscribed in the width/depth rectangle. All roofs must fit inside their level. Existing flat-roof files remain supported. Floors/roofs are concept geometry. This is not structural or code approval.
Read the schema and example. Generate a design using supported types. Validate before writing. Create with a unique idempotency key or read the current project and update with its revision. Keep stable element IDs when editing. Do not overwrite after a conflict without reconciling. Never include credentials in generated JSON or logs. Obtain an authorized API key through the user's normal access flow.