Revit API Guide — Getting Started with BIM Automation

Welcome to the Revit API#

The Revit API (Application Programming Interface) is a powerful toolkit that allows developers to create custom applications, automate tasks, and extend Revit's functionality. Whether you're working with Dynamo scripts, creating add-ins, or building standalone applications, the Revit API provides the foundation for advanced BIM automation.

This is the first article in a three-part series covering Revit API development:

1. Getting Started with BIM Automation (this article)
2. Element Collection with FilteredElementCollector
3. UI Selection Methods

Prerequisites#

Before diving into Revit API development, ensure you have:

• Autodesk Revit installed (2020 or later recommended)
• Basic Programming Knowledge (C# or Python preferred)
• Dynamo for Revit (for visual programming approaches - see section below)
• Visual Studio or Visual Studio Code (only if you want to create C# add-ins)

Dynamo and Revit API: Which to Choose?#

Before writing code, it's important to understand the different ways to automate Revit and when to use each one.

What is Dynamo?#

Dynamo is a visual programming platform integrated into Revit. Instead of writing lines of code, you connect graphical nodes that represent operations. Each node has inputs, executes a specific action, and produces outputs that can be connected to other nodes.

Think of Dynamo as building with LEGO blocks — each block (node) has a clear function, and you connect them to create complex solutions.

When to Use Dynamo#

Dynamo is ideal when:

• You're getting started with BIM automation
• The logic is linear and visual (facade paneling, family placement)
• You want to prototype quickly an idea
• The workflow requires frequent modifications by non-programmers
• You need visual documentation of the process

When to Use Python in Dynamo#

Within Dynamo, you can insert "Python Script" nodes to write code. This is useful when:

• You need complex loops (nested iterations)
• You must manipulate lists in ways not available with standard nodes
• The Dynamo graph is becoming unreadable due to too many connections
• You want to access Revit API functionality not available via nodes

When to Use C# Add-ins#

Creating a complete Revit add-in in C# is necessary when:

• You want to distribute a professional tool with custom interface
• You need maximum performance (processing large models)
• You must integrate with external databases, web APIs, or corporate systems
• The tool will be used by multiple teams and requires controlled updates

Recommended Path for Beginners#

1. Start with Dynamo nodes — learn the basic concepts (elements, parameters, filters)
2. Add Python when necessary — loops, complex conditional logic
3. Move to C# when the tool matures — only if it becomes a corporate product

Most day-to-day BIM automation can be solved with Dynamo + Python.

Your First Revit API Script#

Let's start with a simple example for Dynamo that demonstrates the basic structure of a Revit API operation. This Python script collects all walls in your model and counts them.

How to use this code:

1. Open Dynamo in Revit
2. Create a "Python Script" node (from Core > Scripting library)
3. Copy this code into the node
4. Connect a "Watch" node to the output to see the result

1# Python example for Dynamo
2import clr
3clr.AddReference('RevitAPI')
4clr.AddReference('RevitServices')
5
6from Autodesk.Revit.DB import *
7from RevitServices.Persistence import DocumentManager
8
9# Get the current Revit document
10doc = DocumentManager.Instance.CurrentDBDocument
11
12# Create a FilteredElementCollector to get all walls
13collector = FilteredElementCollector(doc)
14walls = collector.OfClass(Wall).ToElements()
15
16# Output the number of walls found
17wall_count = len(walls)
18print(f"Found {wall_count} walls in the project")
19
20# Dynamo requires output to be assigned to OUT
21OUT = wall_count

What this code does, step by step:

1. Import libraries (clr.AddReference) — tells Python which Revit functionality to load
2. Gets the document (DocumentManager) — connects the script to the open Revit file
3. Creates a collector (FilteredElementCollector) — tool for searching elements
4. Filters by walls (OfClass(Wall)) — limits search to only walls
5. Converts to Python list (.ToElements()) — transforms results into usable format
6. Counts the elements (len()) — standard Python function to count items in a list
7. Returns the result (OUT =) — this is the special variable that Dynamo reads

This simple script demonstrates three fundamental operations:

1. Connecting to the Revit document
2. Collecting elements using FilteredElementCollector
3. Processing the results (counting walls)

Key Concepts Every Beginner Should Know#

Understanding these five concepts is essential for any Revit API development:

1. Document#

The Document is the heart of everything — it represents the open Revit file (.rvt). It contains all elements, views, families, and project settings.

Practical analogy: Think of the Document as the main container. If Revit were a library, the Document would be the entire building — it contains all the books (elements), the shelves (views), and the cataloging system (parameters).

In code, you always get the document like this:

1doc = DocumentManager.Instance.CurrentDBDocument

Why it matters: Every Revit API operation requires a reference to the document. Without it, the code doesn't know which file to work with.

2. Elements#

Everything in Revit is an element — walls, doors, windows, views, sheets, dimensions, even project settings.

Each element has three fundamental components:

• A unique ElementId — like a product's serial number. No two elements ever have the same Id.
• Parameters — the "properties" you see in the Properties panel (height, width, material, etc.)
• A category — the "general type" (Walls, Doors, Windows, etc.)

Practical example:

1# Get an element by its Id
2element = doc.GetElement(ElementId(1234567))
3
4# Read its name
5name = element.Name
6
7# Read its category
8category = element.Category.Name  # e.g., "Walls"

3. FilteredElementCollector#

The FilteredElementCollector is your search engine for the Revit model. It allows you to find specific elements without manually selecting them.

Analogy: Like using a filter on Amazon — you can search for "all laptops" (category), then filter by "price < $1000" (parameter), then by "brand Dell" (another filter).

1# Find all walls
2all_walls = FilteredElementCollector(doc).OfClass(Wall).ToElements()
3
4# Find only doors
5all_doors = FilteredElementCollector(doc).OfCategory(BuiltInCategory.OST_Doors).ToElements()

You'll learn much more about collectors in Part 2: Element Collection.

4. Transactions#

Golden rule: To modify anything in Revit, you need a transaction.

You can read data without transactions (count walls, read parameters), but modifying always requires a transaction (create elements, change parameters, delete objects).

Why do transactions exist?

• Revit tracks all modifications to enable Undo/Redo
• Transactions group multiple modifications into a single reversible action
• If something goes wrong, Revit can automatically "rollback" (undo) everything

Correct structure:

1from Autodesk.Revit.DB import Transaction
2
3# Start a transaction
4t = Transaction(doc, "Operation Name")  # The name appears in Undo
5t.Start()
6
7try:
8    # All modifications go inside here
9    parameter.Set("new value")
10    # ... other modifications ...
11    
12    t.Commit()  # Confirm and save modifications
13except:
14    t.RollBack()  # Undo everything if there's an error

Note: In Dynamo, transactions are often managed automatically. But if you use Python nodes for complex modifications, you must manage them manually.

5. Parameters#

Parameters are the "data" attached to elements — everything you see in the Properties panel.

There are three types:

• Built-in parameters — created by Revit (height, width, volume, material)
• Project parameters — created for that specific project
• Shared parameters — can be reused across different projects

Reading a parameter:

1# Method 1: For built-in parameters (recommended)
2height = element.get_Parameter(BuiltInParameter.WALL_USER_HEIGHT_PARAM)
3height_value = height.AsDouble()  # Returns number
4
5# Method 2: For custom parameters (search by name)
6comment = element.LookupParameter("Comments")
7comment_text = comment.AsString()  # Returns text

Modifying a parameter (requires transaction):

1t = Transaction(doc, "Modify Parameter")
2t.Start()
3try:
4    parameter.Set("new value")
5    t.Commit()
6except:
7    t.RollBack()

Essential Revit API Workflow#

Every Revit API operation follows this pattern:

11. CONNECT    →  Get reference to the Document
22. COLLECT    →  Find elements using FilteredElementCollector
33. PROCESS    →  Read or modify element properties
44. COMMIT     →  Save changes within a Transaction
55. HANDLE     →  Gracefully manage errors

Specialized Guides#

Now that you understand the basics, dive deeper into specific areas of Revit API development:

🔍 Element Collection#

Master the art of finding and filtering elements in your Revit models. The comprehensive Element Collection Guide covers:

• FilteredElementCollector fundamentals
• Category and class-based filtering
• Parameter value filtering
• Geometric filtering (BoundingBox, intersections)
• Performance optimization techniques
• 35+ detailed filtering examples

🖱️ UI Selection Methods#

Create interactive applications that respond to user input. The UI Selection Methods Guide covers:

• Single and multiple element selection
• Face and edge selection
• Custom selection filters
• Advanced user interaction patterns
• Best practices for user experience

Getting Started Tips#

1. Start Small: Begin with simple element collection tasks before moving to complex operations

2. Use Dynamo: Great for prototyping and learning API concepts visually

3. Read the Documentation: Always refer to the official Autodesk Revit API documentation

4. Practice Regularly: The more you code, the more intuitive the API becomes

5. Join the Community: Connect with other developers through forums and user groups

Additional Resources#

• Autodesk Revit API Documentation
• Dynamo Primer
• Building Coder Blog
• Revit API Forum

Coming Soon#

We're constantly expanding this guide with more advanced topics:

📐 Geometry and Modeling#

• Creating and modifying geometric elements
• Working with curves, surfaces, and solids
• Advanced geometric operations
• Family creation and modification

🏗️ Structural Analysis Integration#

• Working with structural elements
• Analysis model creation
• Load application and results processing
• Integration with structural analysis software

📊 Scheduling and Documentation#

• Automated schedule creation
• Custom parameter management
• Drawing sheet automation
• Report generation

What's Next?#

Ready to start your Revit API journey? Continue to the next articles in this series:

• Next: Element Collection with FilteredElementCollector
• Also: UI Selection Methods