Creating Rooms and Inspecting Boundaries with the Revit API: A Beginner’s Guide

What will you learn in this guide?

This guide is for anyone who wants to understand categories and rooms in the Revit API and interpret examples in Autodesk’s developer documentation in the right context. We’ll first look at how a Revit element is classified by category, family, type, and instance. Then we’ll explain two ways to create rooms with the API and the conditions to check when reading room boundaries.

The goal isn’t to provide a ready-made add-in that will work in every project. The code examples show which objects and project conditions the API works with. The examples in the sources are written in C#, so they shouldn’t be pasted into a Python tool as if they were Python code.

Requirements and scope

The Autodesk University beginner course uses Revit, RevitPythonShell, Revit Lookup, and pyRevit. It states that basic Revit knowledge and introductory Python skills are required. This doesn’t mean that the API examples discussed below are also in Python: the code snippets in Autodesk’s room and category documentation are provided in C#.

One of the referenced developer documents is for Revit 2018, while the other is a Revit 2024 documentation page. The sources don’t explain whether these examples are compatible across different Revit versions. Before using an example in a real project, check the API documentation for your target version. The provided sources don’t specify account requirements, current tool versions, or tool licensing terms.

1. Distinguish categories and family structure

A category classifies an element by its general type and determines how Revit handles it. Walls, doors, and rooms are examples of different categories. Categories are associated with functions such as creating schedules, editing parameters, and controlling visibility or graphics.

The family structure is more specific. A Family represents the family as a whole, a FamilySymbol represents a specific type within that family, and a FamilyInstance represents a single instance placed in the project. For example, a door family may contain different types, and each door placed in the project is treated as an instance. In the API, keeping these distinctions in mind helps you avoid confusing an element’s general category with its specific type.

Autodesk’s category example shows how to access the category collection in the active document and select a built-in category. The documentation also warns that category names may vary depending on the language of the Revit interface. To avoid language differences, consider using built-in category identifiers such as BuiltInCategory instead of relying on name strings.

2. Choose a room creation method

The API documentation describes two different scenarios for creating a room. In the first, a room is created using a level and location information. The example expresses the location as a UV value and checks whether the creation result is valid. The key point is that the room creation call depends not only on the room object, but also on information about the level and location where it will be placed.

In the second scenario, a room is first created in a room schedule and associated with a project phase; it is then added to a plan circuit. An important condition is that the room being added to the plan must exist only in the room schedule and not yet be placed in any plan view. The plan circuit is found through the plan topology of the relevant level. When placement succeeds, a model room with the same name and number is created in the view containing the plan circuit.

Before applying either approach, decide what you need: to create a room at a specific point, or to place a room waiting in the schedule into a plan circuit. In the second workflow, skipping the requirement that the room must be in the schedule may prevent the operation from working with the expected inputs.

3. Inspect room boundaries and updates

Room boundaries depend on model elements that form an enclosed area. In Autodesk’s documentation, elements such as walls, model lines, columns, and roofs are listed as examples associated with boundaries. The SpatialElement.GetBoundarySegments() method is used to read boundary segments. The returned data may contain one or more regions and the segments for each region as nested lists.

Boundary data may not be returned in every case. The method may return null if the room isn’t in an enclosed area or exists only in a room schedule. So if no result is returned, check not only the API call but also whether the model forms an enclosed room and whether the room is placed in a plan view.

The Room Bounding setting affects whether elements such as walls, columns, and roofs contribute to room boundaries. Room separation lines can also form boundaries. When an element such as a wall is added through the API, the room boundary may change, so don’t treat boundary data obtained before the change as current afterward. Autodesk’s example shows re-reading the boundaries after the element creation operation is completed within a transaction.

It’s also possible to remove a room from its current location before moving it. The documentation explains that Room.Unplace() removes the room from its location while keeping it available in the project. This requires understanding the difference between deleting the object from the project and changing its placement.

4. Impact on architecture and visualization workflows

Understanding room boundaries and category relationships can help architecture and interior design teams that work with room data, classify model elements, or explore automating repetitive tasks. Because room boundaries depend on surrounding elements in the model and their settings, verify that the model has established these relationships correctly before starting automation.

These sources don’t directly describe rendering or visualization settings. However, model consistency is important in BIM workflows that use room and category data. Before putting an approach into practice, check the Revit version in use, room placement status, the relevant Room Bounding settings, and the project phase. For students, a small test model is a good starting point for observing how boundary data changes when a wall or another surrounding element is modified.

Common mistakes

• Assuming category names are the same in every language of Revit. Autodesk recommends using built-in category identifiers to avoid language differences.

• Expecting boundary segments when the room isn’t in an enclosed area. According to the documentation, the method may return null in this case.

• Placing the room to be added to a plan circuit in a plan view beforehand. The input must exist only in the room schedule.

• Overlooking the Room Bounding status of surrounding elements. This setting determines whether an element contributes to a room boundary.

• Continuing to use old boundary data after creating a new model element. Retrieve the boundary information again after the change is complete.

• Treating C# examples as Python code. Although the sources mention Python tools, the room and category API examples are written in C#.

Next steps

Start by reviewing Autodesk’s category documentation and observing the distinctions among category, family, type, and instance in an existing project. Then compare the room creation scenarios in a test document: creating a room with location information and placing one from a schedule into a plan circuit. Note which view contains the room at each step.

Finally, modify the elements around an enclosed room area and check the boundary data again. This exercise helps you avoid treating the API’s return value as independent of the model state. When moving on to more extensive automation, also consider the element filters, transactions, and user interface topics covered in the Autodesk University beginner course.

Sources and licensing

This guide was written in our own words using Autodesk Revit API developer documentation on rooms (K1), category and family classifications (K2), and Autodesk University’s introductory course on the Revit API (K4). The sources are identified as license=free; since the provided texts don’t name a specific license, no license type is attributed here.