IfcOpenShell API Module System

Quick Reference

Critical Warnings

• ALWAYS use ifcopenshell.api.run() or direct module calls for IFC mutations. NEVER modify entity attributes directly (e.g., wall.Name = "X") — use api.run("attribute.edit_attributes", ...) instead.
• ALWAYS import ifcopenshell.api before calling any API function. The module uses lazy loading; functions are NOT available without this import.
• ALWAYS pass the file (model) object as the first positional argument after the function name in api.run().
• NEVER invent API module or function names. There are exactly 35 modules — see the module table below. Hallucinated calls like api.run("element.create", ...) or api.run("wall.add", ...) do NOT exist.
• ALWAYS use keyword arguments for all parameters after the model. Positional arguments beyond the model are NOT supported.
• NEVER use model.create_entity() for production code. Use api.run("root.create_entity", ...) — it generates GlobalIds, sets ownership, and validates predefined types automatically.
• ALWAYS set up a complete project before creating elements: IfcProject → units → contexts → spatial hierarchy. See the bootstrap pattern below.
• NEVER assume products parameters accept single elements. Since IfcOpenShell v0.8+, most relationship functions expect products as a list, not a single entity.

Decision Tree: Which API Module to Use

What do you need to do?