What's New in the Revit 2018 API

The Revit 2018 API includes numerous exciting enhancements for add-in developers.

The highlights were pointed out in the DevDays Online API news presentation and video recording.

That information is based on the contents of the Revit Platform API Changes and Additions.docx document included with the Revit 2018 software developers kit or SDK available from the Revit Developer Centre.

It is also provided in the section on What's New in the Revit 2018 API help file RevitAPI.chm included with the SDK:

Revit 2018 API help on What's New

For convenient, easy and effective web searching, this blog post provides an online version of that information.

The What's New section always provides very important information, both for discovering and exploring the newly added API functionality and for later reference.

If you encounter any issues migrating your existing add-ins between different versions, this is one of the first places to look.

For detailed information on all other aspects of the Revit API, please refer to the rest of the API documentation and samples provided in the SDK.

The most important things to install and always keep at hand are:

You will need both of these constantly for research on how to solve specific Revit API programming tasks.

More in-depth official explanations and background information is provided by the online Revit API Developers Guide included in the Revit 2018 Help.

What's New in Previous Versions

Here are links to discussions of What's New in the Revit API for previous versions:

Table of Contents

I implemented the Python script number_html_headings.py described below to generate the HTML heading numbering for this table of contents:

API Changes

API enabled in perspective views

Element modifications and contextual commands

Modification of many different object types is now allowed in perspective views. Most commands allowed in 3D orthographic views are now also allowed in perspective views. This includes contextual commands. Annotations are an exception and cannot be created in perspective views.

External commands and applications

External API commands and applications are now enabled by default in perspective views. The following behavior applies:


Several Revit elements can now contain a subdivision known as a Subelement. Subelements provide a way for parts of an element to behave as though they were real elements without incurring the overhead of adding more full elements to the model.

Many Revit features – for example parameters, schedules, and tags – were designed to operate on Elements. As a result, the Revit code needs to represent objects as Elements for them to participate in those features. This can lead to scalability problems, because every Element adds overhead and adding many Elements may decrease the performance of the model.

An alternative is to use Subelements. An element can expose a set of "Subelements" that it contains, specifying characteristics like their category and parameters, and certain Revit capabilities will treat those Subelements the same as ordinary Elements. For example, a Subelement may contribute geometry to the main element and may be able to be selected independently of its parent Element. It will possibly have its own (settable) type as well as an assigned category which can be different from its parent Element.

In the API, the new Subelement class is used to refer to either an Element or a specific subelement of a given Element. It is typically directly related to a Reference to either the Element or the specific subelement.

Note that creation of new Subelements for a given element is not done generically. Instead, the given Element may provide the ability to modify its definition, resulting in the creation of new Subelements.

Examples of Elements which may incorporate Subelements in practice include:

To get access to a particular Subelement, you may use any of the following:

To access the basic Subelement properties, including its category and geometry, use:

To access the Subelement's type, use:

To access the Subelement's parameters, use:

For Elements which allow deletion of individual Subelements, use:

References and selection of subelements

The new enumerated value:

provides the ability to prompt a user to select subelements interactively using Selection.PickObject() or Selection.PickObjects().

The new enumerated value:

identify a reference as a reference to a specific subelement.

The new methods:

provide useful checks related to the contents of a given Reference object, applicable to subelement references as well as other types of references.

Changes to APIs for accessing version

The property:

has been deprecated and replaced by:

The new property returns a string representing the major-minor version number for the Revit application. For example, "2018.0.0". This number is updated for major and minor updates.

In RevitAddinUtility, the similar property:

has been deprecated and replaced by:

This new string property returns a similar major-minor version number for installed Revit versions.

Asset API Changes

The following API classes moved from the Autodesk.Revit.Utility namespace to a new namespace Autodesk.Revit.DB.Visual:

Two AssetProperty properties were deprecated and replaced:

Values for the enumerated type AssetPropertyType were renamed to better adhere to the API standards. Note that corresponding integer values are the same:

  1. APT_Unknown → Unknown
  2. APT_Properties → Properties
  3. APT_Boolean → Boolean
  4. APT_Enum → Enumeration
  5. APT_Integer → Integer
  6. APT_Float → Float
  7. APT_Double → Double1
  8. APT_DoubleArray2d → Double2
  9. APT_DoubleArray3d → Double3
  10. APT_DoubleArray4d → Double4
  11. APT_Double44 → Double44
  12. APT_String → String
  13. APT_Time → Time
  14. N/A
  15. APT_Distance → Distance
  16. APT_Asset → Asset
  17. APT_Reference → Reference
  18. APT_Int64 → Longlong
  19. APT_UInt64 → ULonglong
  20. APT_List → List
  21. APT_FloatArray → Float3

Dynamic Updaters on Reload Latest

Dynamic updaters are now triggered on Reload Latest for the elements added or changed in the central file.

Export to DWG/DXF API change

The new AutoCAD version (R2018) has been added to the ACADVersion enumerated type. This is now the default version used when exporting to DWG and DXF.

UIDocument.PromptForFamilyInstancePlacement() behavioral change

The behavior for UIDocument.PromptForFamilyInstancePlacement() was changed to be same as that of PickObject() methods – the placement operation will be cancelled when the "x" button of Revit is clicked during the placement operation instead of closing Revit directly.

IndependentTag API changes

The new method:

replaces Autodesk.Revit.Creation.Document.NewTag(), which has been marked obsolete. The new version supports tagging of either elements or subelements.

The new method:

returns a reference to the item which has been tagged. This reference may be to a Subelement, which can also be identified by:

The following properties and their methods now throw more informative exceptions:

The new property:

indicates if the leader of the tag has an elbow point or not.

Shared Coordinates API changes

The following properties have been deprecated and replaced:

New DirectShape behaviors

DirectShape elements now support new behaviors. Other than the limitations listed below, no code changes are required to enable these new behaviors for DirectShape elements.

Rebar API Changes

Rebar now supports two different layout options: shape-driven and free-form. Previously, all Rebar elements were shape-driven. The new methods:

Rebar members which are applicable only for shape-driven rebar have been deprecated and replaced with equivalents in the class RebarShapeDrivenAccessor. Specifically, the following members are deprecated:

FabricSheet API Changes

The following methods have been deprecated and replaced:

Structural Section API Changes

Several section properties were moved from subclasses to the base class StructuralSection:

Several specific structural sections offer new constructors with additional input parameters. Their original constructors have been deprecated.

Several new specific structural section classes have been introduced:

In addition, the API for structural sections offers a few other new capabilities:

ElectricalSystem API changes

The following functions have been deprecated and replaced:

Pipe Pressure Loss Calculation change

The methods:

have been deprecated in Revit 2018 and will be removed in the next version of Revit. Custom pipe pressure loss calculations will no longer be supported. Similar functionality can be accessed by setting Autodesk.Revit.DB.Plumbing.PipeSettings.AnalysisForClosedLoopHydronicPipingNetworks.

Corrected names of AutoRouteFailures values

The following BuiltInFailures.AutoRouteFailures values were renamed due to spelling errors:

Obsolete API removal

The following API members and classes which had previously been marked Obsolete have been removed in this release. Consult the API documentation from prior releases for information on the replacements to use:




Enumerated types

API Additions

API to get list of reviewable warnings from a Document

The new method:

returns a list of failure messages generated from persistent (reviewable) warnings accumulated in the document.

API access to FamilyInstance references

The following new methods have been added to enable easy access to FamilyInstance references that correspond to reference planes and reference lines in the family. Some use the options in the new enumeration FamilyInstanceReferenceType as input to identify "Strong" or "Weak" references or specific positional references in each of the 3 coordinate directions (as determined by the possible values of parameter "Is Reference" of reference planes and parameter "Reference" of reference lines in families).

Multistory Stairs API

The new class:

allows users to create stairs that span multiple levels. A multistory stairs element may contain multiple stairs whose extents are governed by base and top levels.

This element will contain one or more Stairs elements. Stairs elements are either a reference instance which is copied to each level covered by groups of identical stairs instances which share the same level height, or individual Stairs instances which are not connected to a group with the same level height. By default, when adding new levels to the multistory stair, new stairs will be added to the group.

For groups of duplicate stairs at different levels, the instances can be found as Subelements of the Stairs element.

Stairs in a connected group can be edited together by modifying the associated Stairs instance. For specific floors that need special designs, stairs can be separated from a group by unpinning the element, changes made to this Stairs will not affect other any other instance in the element, or add the stairs back into the group if needed. However, any changes made to the stair will be lost since the stair's properties will be overridden by the group specifications.

The class has the following methods:

The new property:

indicates the id of the MultistoryStairs element to which the Stairs belong to.

Related to StairsPath functionality for multistory stairs, the new functions:

support creation of new stairs paths in a plan view for stairs instances in a multistory stairs element.

Railings API additions related to MultistoryStairs

The new methods:

provide access to Railing elements which are hosted on members of Multistory stairs.

The method:

Creates new railings on a given level of given multistory stairs – the created railing will be hosted on stairs included in MultistoryStairs element on given level.

The existing method:

now supports MulitstoryStairs elements as input, where the resulting railing will be added on every level of given stairs in multistory stairs.

The existing property:

now supports stairs or stairs components coming from MultistoryStairs elements as well.

Dimension API additions

DimensionEqualityLabelFormating API

The new class:

allows users to set dimension equality formulas for continuous linear or angular dimensions.

New methods and properties include:

The following new methods in DimensionType allow access to equality formulas:

UnitsFormatOptions in DimensionType

The new functions:

allow users to get or set the FormatOptions for a DimensionType.


The new class:

allows users to customize ordinate dimensions.

The new enum:

allows users to choose continuous or segmented line styles for their dimensions.

The new enums:

allows users to orient text in relation to the dimension lines or witness lines.

The new enum:

allows users to control visibility of their dimensions.

New properties in OrdinateDimensionSetting include:

The following new methods in DimensionType allow access to the OrdinateDimensionSetting:

SpatialElementTag API additions

SpatialElementTag is the base element for Room, Area and Space tag classes.

The following new properties have been added:

Geometry API additions

Surface and Face API

The new method:

returns a copy of the Face's surface.

In order to correctly leverage this information, the following properties:

identify whether the face's orientation matches the surface orientation, and whether the surface orientation is the same as or opposite to its parametric orientation.

RevolvedSurface API

The new method:

returns a copy of the profile curve expressed in the world coordinate system.

RuledSurface API

The newly added methods:

check if a point was used to define one of the surface profiles.

Level API addition

The new method:

finds the id of the first available associated floor or structural plan view associated with this level. If there are multiple associated views, Revit will return the first one it finds.

Dockable Frame API Additions

Custom Dockable Panes now support the ability for display of dynamic UI elements, such as web browser controls. This capability should be used in cases where the UI for the pane (layout, buttons etc.) changes dynamically during the lifetime of the Revit session. To use this, implement the new interface:

with a method:

that constructs and returns the WPF Framework element to embedded in the Revit dockable pane.

The new members:

provide the ability for the application to deliver a dynamic framework element to the dockable pane.

The property:

is now allowed to be null, in situations where the FrameworkElement will be dynamically created.

DirectContext3D for display of externally managed 3D graphics in Revit

DirectContext3D is an API for displaying external graphics in the context of a Revit model. The API provides a more connected experience to users who can benefit from the ability to display graphics based on geometry that is either difficult or costly to fully import into Revit.

An external plugin can use DirectContext3D API to render geometry by encoding it inside pairs of vertex and index buffers. The communication between Revit and the plugin is accomplished with the use of the External Service Framework (ESF). Revit's rendering pipeline asks registered servers of the DirectContext3D service to provide the geometry for rendering. Revit informs the plugin about certain rendering state, such as the display style and whether the current rendering pass is for transparent objects. The plugin also communicates certain information to Revit, such as the bounding box of the geometry to be rendered.

The following list contains the major added classes and their descriptions:

View update for DirectContext3D

The new method:

updates all open views in this document after elements have been changed, deleted, selected or de-selected. Graphics in the views are fully redrawn regardless of which elements have changed. This function should only rarely be needed, but might be required when working with graphics drawn from outside of Revit's transactions and elements, for example, when using DirectContext3D.

This function is potentially expensive as many views may be updated at once, including regeneration of view's geometry and redisplay of graphics. Thus for most situations it is recommended that API applications rely on the Revit application framework to update views more deliberately.

Coordination Model elements

Coordination Model elements current can link the graphical contents of Navisworks files and display them in context in the Revit session. These elements leverage the DirectContext3D framework to handle the display of the external graphics, and are the first example of an element which is designated to contain a link to externally managed DirectContext3D graphics (a "DirectContext3D handle" element).

There is no current way to create new Coordination Model or DirectContext3D handle elements via the API. However, you can use the capabilities of the related classes to identify and manipulate these elements. These elements can be accessed from the following new API classes:

Shared Coordinates API additions

Acquire and Publish coordinates API additions

Two new methods allow users to acquire and publish shared coordinates:

SiteLocation API additions

Two new read-only properties have been added to provide information on the geographic coordinate system of a SiteLocation. The geographic coordinate system is imported from a DWG file from AutoCAD or Civil 3D. If the SiteLocation has geographic coordinate system information, the latitude and longitude of the SiteLocation will be updated automatically

when the model's Survey Point is moved.

The new method:

ProjectLocation API additions

The new method:

creates a new ProjectLocation in the document from the given SiteLocation and with the given name.

Revit Link API additions

The new method:

creates a new instance of a linked Revit project (RevitLinkType). Instances will be placed origin-to-origin or by shared coordinates according to the input placement type.

Link API additions

External Resource framework additions

IExternalResourceServer can now provide CAD format links, DWF markups, and IFC links. The following new values have been added to ExternalResourceType.BuiltInExternalResourceTypes:

CADLinkType additions

Several new methods have been added to CADLinkType as part of external resource framework enhancements:

ImportInstance additions

Several new methods have been added to create ImportInstance elements, either from an existing link type or a new link type:

Methods have also been added to create DGN, SAT, and SKP links from external resource locations.

IFC Link API additions

The method:

now has a new version that allows for an ExternalResourceReference to specify the IFC file name, instead of a string.

Workshared operation progress changed events

Subscribe to the Autodesk.Revit.ApplicationServices.Application.WorksharedOperationProgressChanged event to be notified when progress has changed during Collaboration for Revit's synchronizing.

This event consists of several phases. Different event arguments are used during each phase.


The new class:

provides a base class for event arguments for worksharing-based progress events.


The new class:

It has the following properties:


The new class:

It has the following properties:


The new class:

It has the following properties:


The new class:

provides information during the save to central phase of the DocumentSynchronizingWithCentralProgressChanged event.

It has the following properties:


The new class:

provides information about the creation of related files when Collaboration for Revit models are being opened.

It has the following properties:

Events related to linked resources

Subscribe to the events:

to be notified when Revit is just about to open, or has just opened, a linked resource. This event supports linked resources of the following types: Revit; IFC; CAD (DWG, DXF, DGN, SAT).

This event will not be raised if there are no updates for linked CAD or IFC resources. The linked resource cannot be modified during these events.


The new class:

provides information when Revit is just about to open a linked resource.

It has the following properties:


The new class:

provides information when Revit finishes opening a linked resource.

It has the following properties:

Events related to parallel View Export

When exporting multiple views to DWF or DWFx format, Revit uses background processes to compute the exported output of several views in parallel. Two events are now available on the Application class to receive progress updates during a parallel export operation:

These two events are raised only during accelerated export jobs, in which views are exported in parallel using a background process. Accelerated export only occurs when exporting to DWF formats and not combining views into a single file.

DWG export API additions

The new enumerated value:

specified an export where all colors from the Revit project will be exported as 24-bit RGB values as specified in view (where ExportColorMode.TrueColor indicates that all colors from the Revit project will be exported as 24-bit RGB values as specified in object styles)

The new properties:

allow assignment of a color that will be set as hatch background color on the exported hatch.

ExportDWGSettings API additions

Two new methods have been added to ExportDWGSettings:

Note that these functions cannot return in-session settings. To access the in-session settings, save them with a name.

Part API additions

The new methods:

provide further capabilities to access and manipulate the offset applied to a given face of a Part element.

Freeform Rebar API additions

The new methods:

Create a freeform rebar instance where bars are created along the path of the input curves. Constraints cannot later be added to this rebar.

Freeform rebar instances have properties accessible from the RebarFreeFormAccessor class, which can be obtained from:

The new members of this accessor class allow you to change the bar curves only for unconstrained rebar:

They also provide access to layout, distribution path and hook properties of the rebar, if applicable:

Custom Service for Freeform Rebar Definition

The new interface class:

represents an interface that can be overridden to drive the generation and update of freeform rebar geometry. The interface features several methods:

If a position for a handle isn't provided, that handle will not be represented on screen while edit constraints.

The interfaces methods each provide an input argument which carries data needed for the calculation, as well as the results. These new argument classes are:

You can programmatically create a freeform Rebar whose geometry and constraints are governed by the external service using:

You can convert a FreeForm rebar governed by an external service to an unconstrained element using:

In order to access and modify constraints associated to any custom handles associated to the service-driven freeform Rebar, you may use the members of the RebarConstrainedHandle class:

and use the new members of RebarConstraint and RebarConstraintsManager:

HVACSpaceType and Space air ventilation API

The following new properties have been added to Autodesk.Revit.DB.Space:

Energy Analysis API additions

Several new classes have been added to allow better control over spaces when doing energy analysis.

The new class:

is the base class for HVACLoadSpaceType and HVACLoadBuildingType.

It has the following properties:

The new class:

allows users to set the usage type associated with the space, such as 'Dining Area' or 'Lobby'.

It has the following methods and properties:

The new class:

allows users to set the energy analysis usage type associated with a building, such as 'Museum' or 'Office'.

It has the following methods and properties:

The new properties:

allow users to set the energy analysis type associated with a space or mass zone.

Note that these classes are not ElementTypes. They represent properties of a space or building when doing energy analysis, and do not have instances.

Electrical API additions

Electrical Circuit Path API

The new API members:

support different options and operations related to electrical circuit paths.

PanelScheduleView API

The following new methods handle space or spare circuit operations:

MEPAnalyticalConnection API additions

Two new classes have been added to allow API users to create analytical connections between elements. The behavior is the same as in Revit's UI.

The new class:

represents an analytical element that connected mechanical equipment to a piping network. The analytical connection can be used to create a network even if no real pipes are placed yet. It enables the fast establishment of a piping network to analyze the flow and pressure, especially at the early stage of the design process.

It has the following methods:

The new class:

is the type element of an MEPAnalyticalConnection. Its pressure loss value is included in the network critical path calculation.

It has the following methods and properties:

The new property:

indicates whether to enable analysis for closed loop hydronic piping networks in the background.

Fabrication API additions

Hanger Rod additions

The following new methods and properties allow better control of hanger rod lengths:

The new property:

allows users to get or set the support rod kit override. This gives the user better control over hanger rod thicknesses.

Placing and splitting fabrication parts

The following methods allow placing and splitting fabrication parts:

Fabrication Part export additions

The new method:

exports Fabrication parts to PCF format.

The new property:

allows control over Spool names in PCF output.

Fabrication Part status additions

Two properties were added to FabricationPart to allow the user to query and set the part fabrication status field:

Fabrication part comparison

The new method:

compares basic dimensional information of two fabrication parts but also allows the user to specify additional fabrication data to ignore. This allows users to compare parts including fabrication data not exposed in Revit.

Fabrication Part ancillary usage additions

The new method:

gets a list of FabricationAncillaryUsage structures that lists the ancillaries that the fabrication part uses. This method can be used to populate cut lists and procure ancillaries needed to fabricate and install the fabrication part.

The new class:

contains the ancillary usage data. It has the following read-only properties:

Fabrication Part custom data additions

The following methods allow access to Fabrication Part custom data defined per part. This can be used for querying and changing values:

FabricationConfiguration additions

New methods have been added to access fabrication data defined by the currently loaded fabrication configuration. These can be used to query what fabrication data is available for fabrication parts to use:

Routing exclusions additions

The following methods allow users to override routing exclusions:

FabricationServiceButton addition

The new property:

returns true if all conditions of the fabrication service button are straight pieces. This indicates the button is suitable for use with multi-point routing, among other uses.

Python Automatic HTML Heading Numbering Script

The following Python script number_html_headings.py automatically adds HTML hypertext reference A tags to an HTML file sequentially numbering up to ten levels of headings:

# number_html_headings.py - add numbering to HTML headings
# Copyright (C) 2017-04-25 by Jeremy Tammik, Autodesk Inc. 

filename = 'Revit_Platform_API_Changes_and_Additions_2018_03.htm'

filepath = '/a/doc/revit/tbc/git/a/zip/' + filename

nlevels = 10 # max heading level to number

ih = [] # current count for each heading level

for i in range(nlevels):

def filereadlines( filename ):
  f = open( filename )
  data = f.readlines()
  return data

if __name__ == '__main__':

  def main():
    lines = filereadlines( filepath )
    for line in lines:
      line = line.strip()
      a = ''
      if line.startswith('<h'):
        level = int(line[2])
        ih[level-1] = ih[level-1] + 1
        a = '.'.join( [str(ih[l]) for l in range(level)] )
        a = '<a name="' + a + '"></a>'
      print a + line


I used it to generate the table of contents above.

It handles up to ten heading levels H1..H9 and assumes the heading tags are all at the beginning of a line.

I implemented it for and tested it on the input file Revit_Platform_API_Changes_and_Additions_2018_03.htm, generating the output file Revit_Platform_API_Changes_and_Additions_2018_04.htm.

It will gladden me if you can make use of this as well.