Blender Core Api

blender-core-api

Quick Reference

bpy Module Hierarchy

| Module | Purpose | Example | |--------|---------|---------| | bpy.data | All blend-file data (ID data blocks) | bpy.data.objects["Cube"] | | bpy.context | Current state (active object, mode, selection) | bpy.context.active_object | | bpy.ops | Operators with undo support | bpy.ops.mesh.primitive_cube_add() | | bpy.types | Type definitions for all Blender structs | class MyOp(bpy.types.Operator): | | bpy.props | Property definitions for custom data | bpy.props.FloatProperty() | | bpy.utils | Utility functions (registration, paths) | bpy.utils.register_class(cls) | | bpy.app | Application info (version, handlers) | bpy.app.version | | bpy.path | Blender-aware path utilities | bpy.path.abspath("//file.png") | | bpy.msgbus | Message bus for property notifications | bpy.msgbus.subscribe_rna() |

bpy.data Collections (all versions)

bpy.data
├── .objects      ├── .meshes       ├── .materials    ├── .scenes
├── .collections  ├── .node_groups  ├── .images       ├── .textures
├── .lights       ├── .cameras      ├── .curves       ├── .armatures
├── .worlds       ├── .actions      └── ... (30+ total collection types)

Critical Warnings

NEVER cache bpy.data object references across undo operations — undo invalidates all pointers.

NEVER call bpy.ops.* from a background thread — all bpy calls MUST run on the main thread.

NEVER use dict context overrides in Blender 4.0+ — use context.temp_override() instead.

NEVER modify scene data inside Panel.draw() — draw callbacks are read-only.

NEVER access mesh.vertices while in Edit Mode — the data is not synchronized. Use bmesh.from_edit_mesh() instead.

---

Essential Patterns

Pattern 1: Data Access vs. Operators

Use bpy.data for direct data manipulation (fast, no undo). Use bpy.ops only when undo support or user-facing actions are required.

# Blender 3.x/4.x/5.x: CORRECT: direct data access (no context required)
obj = bpy.data.objects.get("Cube")
if obj:
    obj.location = (1.0, 0.0, 0.0)

# Blender 3.x/4.x/5.x: CORRECT: operator when undo is needed
bpy.ops.object.location_clear()  # Requires correct context

Pattern 2: Context Overrides (version-critical)

# Blender 3.x ONLY: BROKEN in 4.0+
override = bpy.context.copy()
override['active_object'] = obj
bpy.ops.object.modifier_apply(override, modifier="Subsurf")  # REMOVED in 4.0

# Blender 3.2+ and 4.x/5.x: CORRECT
with bpy.context.temp_override(object=obj, active_object=obj):
    bpy.ops.object.modifier_apply(modifier="Subsurf")

# Blender 4.x/5.x: Override area for viewport operators
for window in bpy.context.window_manager.windows:
    for area in window.screen.areas:
        if area.type == 'VIEW_3D':
            with bpy.context.temp_override(window=window, area=area):
                bpy.ops.view3d.snap_cursor_to_center()
            break

Pattern 3: ID Data Block Lifecycle

# Blender 3.x/4.x/5.x: create, link, manage user count
mesh = bpy.data.meshes.new("MyMesh")         # Creates data block
obj = bpy.data.objects.new("MyObject", mesh) # Creates object referencing mesh
bpy.context.collection.objects.link(obj)     # REQUIRED: link to scene collection

# Prevent orphaned data from being purged on save
mesh.use_fake_user = True  # Keeps data even with zero users

# Remove data block
bpy.data.meshes.remove(mesh)

Pattern 4: Dependency Graph

# Blender 3.x/4.x/5.x: get evaluated (post-modifier) data
depsgraph = bpy.context.evaluated_depsgraph_get()
obj_eval = obj.evaluated_get(depsgraph)       # Evaluated object
mesh_eval = obj_eval.to_mesh()                # Evaluated mesh (read-only)
# ... read mesh_eval ...
obj_eval.to_mesh_clear()                      # ALWAYS clean up

# Iterate ALL instances (including collection/particle instances)
for instance in depsgraph.object_instances:
    obj = instance.object          # Evaluated object
    matrix = instance.matrix_world # World transform
    is_inst = instance.is_instance # True for non-base instances

---

Common Operations

Object Selection and Activation

# Blender 3.x/4.x/5.x: correct API (2.80+ style)
obj.select_set(True)                              # NOT obj.select = True
bpy.context.view_layer.objects.active = obj       # NOT scene.objects.active

RNA Introspection

# Blender 3.x/4.x/5.x: inspect properties via RNA
obj = bpy.context.active_object
for prop in obj.bl_rna.properties:
    print(f"{prop.identifier}: {prop.type}")

# Get type info on a specific property
prop = obj.bl_rna.properties['location']
print(prop.array_length)  # 3
print(prop.subtype)       # 'TRANSLATION'

Application Handlers

# Blender 3.x/4.x/5.x
from bpy.app.handlers import persistent

@persistent  # Decorator required to survive file load
def on_depsgraph_update(scene, depsgraph):
    for update in depsgraph.updates:
        if update.is_updated_geometry:
            print(f"Geometry changed: {update.id.name}")

bpy.app.handlers.depsgraph_update_post.append(on_depsgraph_update)

# Unregister in addon unregister():
bpy.app.handlers.depsgraph_update_post.remove(on_depsgraph_update)

Version Detection

# Blender 3.x/4.x/5.x
major, minor, patch = bpy.app.version  # e.g., (4, 2, 0)

if bpy.app.version >= (4, 0, 0):
    # Use temp_override, NodeTree.interface, bone.collections
    pass
if bpy.app.version >= (5, 0, 0):
    # Use gpu module exclusively for drawing
    pass

Creating and Linking Objects

# Blender 3.x/4.x/5.x: complete pattern
mesh = bpy.data.meshes.new("MyMesh")
verts = [(0, 0, 0), (1, 0, 0), (1, 1, 0), (0, 1, 0)]
faces = [(0, 1, 2, 3)]
mesh.from_pydata(verts, [], faces)
mesh.update()  # ALWAYS call after from_pydata

obj = bpy.data.objects.new("MyObject", mesh)
bpy.context.collection.objects.link(obj)  # REQUIRED — objects without links are invisible

Restricted Contexts

| Callback | Forbidden Operations | |----------|---------------------| | Panel.draw() | bpy.ops.*, property modification | | depsgraph_update_post | Adding/removing objects, scene mutation | | render_pre/post | Most bpy.ops.* | | Background mode | All viewport operators, OpenGL |

---

Version-Specific Migration Rules

| Feature | Blender 3.x | Blender 4.0+ | |---------|-------------|--------------| | Context override | bpy.ops.foo(override_dict, ...) | context.temp_override(...) | | Mesh bevel weight | edge.bevel_weight | mesh.attributes["bevel_weight_edge"] | | Mesh crease | edge.crease | mesh.attributes["crease_edge"] | | Node group sockets | node_group.inputs.new(...) | node_group.interface.new_socket(...) | | Bone layers | bone.layers[i] | bone.collections |

| Feature | Blender 4.x | Blender 5.0+ | |---------|-------------|--------------| | Drawing | bgl module (deprecated) | gpu module (REQUIRED) | | Compositing | scene.node_tree | scene.compositing_node_group | | EEVEE identifier | BLENDER_EEVEE or BLENDER_EEVEE_NEXT | BLENDER_EEVEE |

---

Reference Links

• [references/methods.md](references/methods.md) — Complete API signatures for bpy.data, bpy.context, bpy.ops, bpy.types, Depsgraph
• [references/examples.md](references/examples.md) — Working code examples verified against official documentation
• [references/anti-patterns.md](references/anti-patterns.md) — What NOT to do, with WHY explanations

Official Sources

• https://docs.blender.org/api/current/info_quickstart.html
• https://docs.blender.org/api/current/info_overview.html
• https://docs.blender.org/api/current/bpy.context.html
• https://docs.blender.org/api/current/bpy.types.Depsgraph.html
• https://docs.blender.org/api/current/bpy.types.Context.html

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Impertio-Studio
• Source: Impertio-Studio/Blender-Bonsai-ifcOpenshell-Sverchok-Claude-Skill-Package
• License: MIT
• Homepage: https://github.com/OpenAEC-Foundation

Install and usage instructions live in the source repository linked above.