Introduction

Modern Revit development sits at the intersection of BIM knowledge, software architecture, and a fast-moving API surface. Autodesk describes the Revit API as a .NET API for automating repetitive tasks and extending Revit functionality in areas such as simulation, construction, and model workflows. A Revit API assistant designed for professional plugin development should therefore behave less like a generic chatbot and more like a version-aware development partner that understands Autodesk.Revit.DB, Autodesk.Revit.UI, transaction safety, model context, and the practical realities of deploying add-ins.

This article walks through the architecture of a live-documentation Revit API assistant – a working prototype is available as the Revit API Assistant on ChatGPT – and shows how it should reason about commands, collectors, transactions, modeless UI, and Autodesk Platform Services automation. It also explains why this kind of assistant matters for BIM teams and how Graph approaches the broader problem of secure, domain-specific AI assistants for AECO and manufacturing.

Why A Revit Assistant Needs To Be Different

A generic coding assistant treats Revit add-in code like any other C# project. That mostly works – until it doesn't. Revit add-ins fail in characteristic ways:

• An overload that exists in Revit 2025 but not in 2022.

• A Transaction opened in the wrong context, silently dropped, or nested incorrectly inside a TransactionGroup.

• A modeless WPF window that calls into the Revit document directly and crashes Revit with InvalidOperationException: Attempt to modify the model outside of transaction.

• A FilteredElementCollector that is iterated multiple times or wrapped in LINQ before native filters are applied, slowing the entire command on large models.

• A .addin manifest pointing to the wrong target framework or assembly path, so the add-in never loads.

A useful assistant has to internalize all of this. It is closer to a senior plugin engineer with the API documentation open than it is to a code completion model.

Core Design

The assistant's design is built around four layers: conversation, retrieval, reasoning, and code generation.

Conversation Layer

The conversation layer understands the developer's goal: "collect all doors," "renumber rooms," "create sheets," "sync parameters," "build a WPF modeless dialog," or "convert a Dynamo prototype into a compiled add-in." It should also detect the user's preferred implementation style, such as C#, pyRevit-style Python, Dynamo Python, or a larger Visual Studio add-in architecture.

This layer is also responsible for clarifying context that materially changes the answer:

• Which Revit version is the user targeting? (2022, 2024, 2025+)

• Is the project a single IExternalCommand or an IExternalApplication with a Ribbon panel?

• Does the user need a modal dialog, a modeless dock panel, or a background task?

• Is the workflow local, or destined for Autodesk Platform Services Design Automation for Revit?

Retrieval Layer

The retrieval layer is the critical safety layer. In this design, the assistant has an action such as fetchLatestRevitDocs(query) that retrieves live Autodesk and Revit API documentation before recommending class names, signatures, overloads, or version-specific behavior. This matters because Revit plugins are tightly coupled to API versions, assembly references, and runtime behavior. A response about FilteredElementCollector, for example, should verify available constructors and methods before generating code.

The retrieval layer should also cover:

• The Revit API .chm reference for each supported version.

• Autodesk Platform Services documentation for Design Automation, Model Derivative, and Data Management APIs.

• pyRevit and RevitPythonShell conventions when Python is the chosen output.

• Migration notes between Revit versions (e.g. Element.Parameters deprecations, Document.NewFamilyInstance overload shifts).

Reasoning Layer

The reasoning layer maps the user's request to Revit's execution model. It decides whether the task needs an IExternalCommand, an IExternalApplication, an ExternalEvent, a Transaction, a TransactionGroup, a selection filter, a parameter binding workflow, or a cloud-side Automation API process.

Code Generation Layer

The code-generation layer produces implementation-ready snippets, not isolated fragments. A useful assistant should include namespaces, transaction handling, error handling, comments, and notes about Revit-specific constraints. For example, a command that modifies model elements must account for Revit's transaction model: Revit API documentation describes Transaction as the object that guards model changes, and changes only become part of the document after commit.

A generated IExternalCommand skeleton should always include the TransactionMode attribute, a clear separation between data collection (read-only) and modification (inside a Transaction), and explicit exception handling:

Capabilities

A strong Revit API assistant can help with entry-level tasks such as explaining Document, UIDocument, UIApplication, ElementId, and BuiltInCategory. It can also handle advanced development topics such as modeless WPF interfaces, failure processing, extensible storage, worksharing metadata, family creation, geometry extraction, parameter binding, and add-in deployment.

Command Level

At the command level, the assistant should understand IExternalCommand, the standard entry point for many Revit add-ins. Revit API documentation describes IExternalCommand as the interface implemented to provide an external command, with access to ExternalCommandData, the active UIDocument, and the active Document.

A fully working "collect all walls" example, written the way the assistant should produce it for a beginner:

Notice the deliberate choices: TransactionMode.ReadOnly because nothing is being modified, WhereElementIsNotElementType() to exclude wall types, and explicit Cast() instead of OfType() because the collector is already category-filtered.

Data-Query Level

At the data-query level, the assistant should guide developers toward efficient use of FilteredElementCollector. The Revit API documentation describes this class as a way to search, filter, and iterate through sets of elements, with constructors for document-wide, view-specific, element-id-specific, and Revit-link-related collection. It also notes that native filters should be applied before LINQ when possible for better performance.

Good pattern:

Anti-pattern the assistant should flag:

Modification Level

For an intermediate task like "renumber rooms by level," the assistant should produce a complete, transaction-safe command:

The two-phase approach avoids the classic "number already in use" exception when two rooms swap numbers, and TransactionGroup.Assimilate collapses both transactions into a single undo step for the user.

UI Integration Level

At the UI-integration level, the assistant should know when ExternalEvent is required. For modeless dialogs, background UI interactions, or WPF panels that need to safely call back into Revit, ExternalEvent allows an external owner to signal Revit, after which Revit executes the handler in the proper API context.

A reusable handler with an action queue:

The modeless WPF panel just enqueues actions and raises the event:

Automation Level

At the automation level, the assistant can extend beyond desktop add-ins. Autodesk Platform Services Automation APIs support batch processing of design files, parameter adjustments, drawing generation, data extraction, and execution of CAD-engine workflows including Revit-related automation.

A Design Automation for Revit application entry point looks structurally similar to a desktop add-in, but driven by DesignAutomationBridge:

This distinction – desktop vs. cloud – is one the assistant should surface proactively. "Batch-upgrade five hundred Revit files" is not a desktop add-in task; it is a Design Automation workflow with a different deployment model.

Example Uses

A beginner might ask: "How do I collect all walls in the active model?" The assistant would retrieve the latest documentation for FilteredElementCollector, confirm the relevant methods, and return a C# snippet using OfCategory(BuiltInCategory.OST_Walls), WhereElementIsNotElementType(), and safe casting – like the example earlier in this article.

An intermediate developer might ask: "Create a button that renumbers rooms by level." The assistant would suggest an IExternalCommand, collect Room elements, sort them by level and location, open a Transaction, update the room number parameter, and handle duplicate or read-only parameter cases.

An advanced developer might ask: "Build a modeless QA panel that lets users select warnings and fix them." The assistant would recommend a WPF UI, an ExternalEvent handler, a queue of user actions, and transaction-scoped fix operations, because modeless UI code should not directly modify the Revit document outside a valid Revit API context.

A BIM manager might ask: "Extract all door fire ratings and compare them against a rule set." The assistant could propose a read-only collector workflow, parameter normalization, schedule-compatible output, and optional export to CSV or an internal QA dashboard:

A platform team might ask: "Can we batch-upgrade and audit hundreds of Revit files?" The assistant would move the discussion toward APS Automation API, where repeatable design-file processing can be run at scale rather than manually opening every project in desktop Revit.

A toolchain team might ask: "Generate a .addin manifest for our Ribbon application." The assistant should produce something deployable:

Future Potential Additions

The most valuable future addition is version-aware code generation. Instead of saying "use this method," the assistant should say: "For Revit 2024 and later, this overload is available; for earlier versions, use this fallback." The live-documentation action makes that practical:

Another addition is project-context awareness. The assistant could inspect a plugin's folder structure, .addin manifest, target framework, NuGet references, Revit version, and existing command classes, then generate code that fits the project rather than producing generic snippets.

A third addition is model-aware diagnostics. With safe access to exported model metadata, schedules, warnings, or element summaries, the assistant could recommend targeted fixes: unused families, inconsistent shared parameters, missing classification values, unplaced rooms, duplicate marks, or invalid MEP connectors.

A fourth addition is automated testing support. Revit plugin development is difficult to test because much of the API expects a Revit-controlled context. A future assistant could generate testable service layers, isolate pure business logic, and distinguish between code that must run inside Revit and code that can be unit-tested externally. A practical pattern:

A fifth addition is BIM standards enforcement. The assistant could translate office standards into executable checks: naming conventions, sheet numbering rules, parameter requirements, classification systems, export rules, IFC mapping checks, and model health reports.

Why Live Documentation Matters

Without live documentation retrieval, an assistant can easily produce code that looks correct but fails because of an overload mismatch, a deprecated API pattern, a changed target framework, or a version-specific Revit behavior. With fetchLatestRevitDocs(query), the assistant becomes more reliable: it can verify the current API surface, cite the relevant class or method, and explain why a particular implementation is valid for the user's Revit version.

For Revit development, that distinction is important. A small error in transaction handling can prevent model modification. A poorly filtered collector can slow a large project. A modeless UI that bypasses ExternalEvent can fail unpredictably. A version mismatch can break deployment across an office.

You can try the prototype here: Revit API Assistant on ChatGPT.

How Graph Builds Assistants Like This

Graph is a Copenhagen-based deep tech consultancy and product studio working at the intersection of applied AI, computational geometry, robotics, and full-stack software engineering for AECO, manufacturing, and capital markets. Revit and broader BIM tooling is a recurring part of that work: Graph builds Revit add-ins and Dynamo extensions, Grasshopper and Rhino plugins via RhinoCommon, Mastercam and Inventor extensions, and parametric robot control through its proprietary Axis framework for ABB, KUKA, UR, and Fanuc.

Alongside the design and fabrication tooling, Graph builds domain-specific AI assistants:

• Atlas – a multi-agent career and technical mentor built on Vertex AI, used inside Graph Labs to guide computational designers into software and AI engineering.

• Clara – Graph's internal AI used across email, scheduling, knowledge retrieval, and assistant-driven product workflows, including the Graph iOS app.

• GPTimber – an AI-powered virtual colleague embedded in CAD environments inside the Fabrify platform, advising on fabricability, transportability, grid spans, tolerances, and assembly for timber construction.

• Custom GPTs for clients, including domain-specific copywriters and technical assistants like the Revit API Assistant referenced above.

This work sits on top of a strong opinion about secure inference. Many of Graph's clients in defense, construction, and regulated industries cannot send proprietary models, parameters, schedules, or geometry to public LLM endpoints. Graph addresses this with:

• EU-resident deployments on Google Cloud Vertex AI and Azure OpenAI with data-residency and opt-out-from-training guarantees.

• Private model hosting for sensitive workloads, including on-prem or VPC-isolated inference with strict role-based access control.

• Retrieval-augmented architectures where source documents – office standards, Revit API references, project schedules, fabrication rules – stay inside the client's tenant and are surfaced to the model through scoped retrieval rather than fine-tuning.

• Structured outputs and tool-call validation so that assistants can drive concrete actions (write a parameter, generate a sheet, queue a Design Automation work item) with explainable, auditable behaviour.

A Revit API assistant is a useful microcosm of this larger philosophy. It demonstrates how an LLM, a retrieval layer over authoritative documentation, a domain-aware reasoning layer, and disciplined code generation can become a real engineering tool rather than a novelty.

Conclusion

The ideal Revit API assistant is not just a code generator. It is a documentation-aware, version-sensitive, BIM-literate development partner. It understands how Revit commands enter the API, how documents are safely modified, how elements are collected efficiently, how modeless interfaces communicate with Revit, and when local automation should become cloud-scale processing.

With live documentation retrieval, project-context awareness, and deeper testing support, such an assistant can help beginners learn the API, help experienced developers move faster, and help BIM teams turn repetitive Revit work into reliable, maintainable software.

Try the live prototype here: Revit API Assistant on ChatGPT. To talk about custom assistants, secure inference, or BIM-and-fabrication AI tooling for your team, see graphtechnologies.xyz.

Appendix: A C# Revit Automation Cookbook

This appendix collects practical, copy-pasteable Revit C# snippets the assistant should be able to produce, explain, and adapt. The examples assume a desktop Revit add-in referencing RevitAPI.dll and RevitAPIUI.dll. The conventions are consistent throughout:

• Most button-triggered automations are IExternalCommand implementations.

• Any model change happens inside a Transaction.

• FilteredElementCollector is the standard tool for finding elements.

• ExternalEvent is the safe pattern for modeless UI calling back into Revit.

For version-sensitive snippets, the assistant should consult live documentation before answering, for example:

A0. Common using Block

This is the standard set of namespaces used by most command files in the cookbook. Putting them at the top of every file keeps the code samples below short and focused on the Revit logic rather than imports.

A1. Minimal External Command

The smallest viable IExternalCommand. It opens the active document, shows its title in a TaskDialog, and exits successfully. Every other command in the cookbook follows this same shape.

A2. Count All Walls In The Active Model

A read-only example showing the canonical FilteredElementCollector pattern: filter by category, exclude element types (so you only get instances), and materialise the result. Use this shape any time you need "all X in the model."

A3. Export Door Data To CSV

A practical BIM data-extraction command. It collects all door instances, reads a handful of parameters (Mark, Family, Type, Level, Fire Rating), and writes a UTF-8 CSV to the user's desktop. The GetParameterValue helper centralises parameter reading across storage types; the Csv helper safely quotes values so commas and quotes inside parameter values don't break the file.

A4. Bulk-Set An Instance Parameter On All Doors

The canonical write-transaction example. It collects all doors, opens a single Transaction, and writes a QA_Checked = "Yes" value on every door that exposes a writable parameter with that name. TrySetParameter handles all storage types and silently skips read-only or missing parameters, returning a counter for reporting.

A5. Find Elements Missing Required Data And Select Them

A QA-style command. It collects all doors that have no Fire Rating value and selects them in the UI so the modeller can see exactly what needs attention. This is a useful template for any "find non-compliant elements" workflow.

A6. Renumber Rooms By Level And Position

A classic BIM cleanup task. Rooms are ordered by level elevation, then by Y then X position, then renumbered as zero-padded sequential strings. Each renumber happens inside a single transaction. Note: for production use, consider the two-phase "park then assign" pattern shown earlier in the article to avoid number collisions during the rewrite.

A7. Create Floor Plans For All Levels

Automates view creation. The command finds a floor-plan ViewFamilyType, iterates over every Level, and creates a named floor plan for any level that doesn't already have one. ViewPlan.Create is the supported entry point for new plan views.

A8. Create Sheets From The First Available Title Block

Generates blank sheets using whatever title-block family the project ships with. ViewSheet.Create accepts a title-block family symbol id; for projects with several title blocks, pick the right one rather than FirstOrDefault.

A9. Place Floor Plan Views On New Sheets

Extends the previous example: for each of the first five floor-plan views, create a sheet and drop the view onto it as a viewport. Viewport.CanAddViewToSheet guards against re-placing a view that's already on another sheet.

A10. Duplicate The Active View With Detailing

Duplicates the currently active view including its view-specific annotations ("With Detailing"). The command checks CanViewBeDuplicated before attempting, and switches the active view to the new copy so the user sees the result immediately.

A11. Create A Basic Door Schedule

Uses ViewSchedule.CreateSchedule to build a category-based schedule and progressively adds the fields you want shown. AddFieldIfAvailable makes the command resilient when a particular field isn't available in the current project.

A12. Hide Grids And Levels In The Active View

A view-cleanup command that hides annotation categories in whatever view is currently active. CanCategoryBeHidden is the safety check – not every category can be hidden in every view type.

A13. Copy Selected Elements By A Fixed Offset

Wraps ElementTransformUtils.CopyElements, the supported way to duplicate elements with a translation vector. The new ids are returned by the API and immediately re-selected so the user sees the copies.

A14. Delete Imported CAD Files

A destructive cleanup command. It finds every ImportInstance (both linked and imported CAD content), asks the user to confirm, and deletes them in a single transaction. Always include explicit confirmation for destructive automations.

A15. Modeless UI-Safe ExternalEvent Pattern

The reference implementation for letting a long-lived WPF window mutate the Revit document safely. The handler does all model work inside a Transaction; the window simply sets state on the handler and raises the event. Without this pattern, calls from a modeless UI thread will throw Attempt to modify the model outside of transaction.

A WPF window owns one handler and one ExternalEvent, both created once. The button click just stages state and raises the event – it never touches the document directly.

A16. Create A Ribbon Tab And Buttons

A minimal IExternalApplication that adds a "Graph Tools" tab with two buttons on first startup. Each PushButtonData points at a fully-qualified class name in this assembly; Revit will instantiate that class as an IExternalCommand on click.

A matching .addin manifest, dropped into %ProgramData%\Autodesk\Revit\Addins\\, tells Revit where to load the assembly from. The AddInId GUID must be unique per add-in.

A17. Suggested Folder Structure

For anything beyond a couple of commands, separating commands, services, UI, and external events keeps the codebase maintainable and testable. Pure business rules belong in Services/, isolated from Revit-specific types so they can be unit-tested outside the host.

For production automations, keep Revit API calls inside command and service classes, keep WPF code-behind thin, and isolate pure business rules so they can be unit-tested outside Revit – exactly the testability story the assistant should encourage when generating new code.