REST API Reference
For more information about schema extensions, refer to the Extension Types section in the API Basics
Hubs
For dealing with end-user data, hubs are the main entry point to the Data Management API and represent a space where projects are hosted. The following are the supported endpoints and methods related to Hubs.
| Endpoint | Description |
|---|---|
| GET hubs | Returns a collection of accessible hubs for this member. Hubs represent BIM 360 Team hubs, Fusion Team hubs (formerly known as A360 Team hubs), A360 Personal hubs, or BIM 360 Docs accounts. |
| GET hubs/:hub_id | Returns data on a specific hub_id. |
Projects
Projects contain the entry points of each of the individual projects a hub is hosting. The following are the supported endpoints and methods related to projects.
| Endpoint | Description |
|---|---|
| GET hubs/:hub_id/projects | Returns a collection of projects for a given hub_id. |
| GET hubs/:hub_id/projects/:project_id | Returns a project for a given project_id. |
| GET hubs/:hub_id/projects/:project_id/hub | Returns the hub for a given project_id. |
| GET hubs/:hub_id/projects/:project_id/topFolders | Returns the details of the highest level folders the user has access to for a given project. |
| GET projects/:project_id/downloads/:download_id | Returns the details for a specific download. |
| GET projects/:project_id/jobs/:job_id | Returns the job_id object. |
| POST projects/:project_id/downloads | Request the creation of a new download for a specific and supported file type. |
| POST projects/:project_id/storage | Creates a storage location in the OSS where data can be uploaded to. |
Folders
Folders are collections of resources related to a project. Every project has a root folder within which all project data is contained. Folders can contain other items like files or sub-folders. The following are the supported endpoints and methods related to folders.
| Endpoint | Description |
|---|---|
| GET projects/:project_id/folders/:folder_id | Returns the folder by ID for any folder within a given project. |
| GET projects/:project_id/folders/:folder_id/contents | Returns a collection of items and folders within a folder. |
| GET projects/:project_id/folders/:folder_id/parent | Returns the parent folder (if it exists). |
| GET projects/:project_id/folders/:folder_id/refs | Returns the resources (items, folders, and versions) that have a custom relationship with the given folder_id. |
| GET projects/:project_id/folders/:folder_id/search | Filters the data of a folder and recursively in the subfolders of any project accessible to you, using the filter query string parameter. |
| GET projects/:project_id/folders/:folder_id/relationships/links | Returns a collection of links for the given folder_id. |
| GET projects/:project_id/folders/:folder_id/relationships/refs | Returns the custom relationships that are associated with the given folder_id. |
| PATCH projects/:project_id/folders/:folder_id | Modifies folder names. You can also use this endpoint to delete and restore BIM 360 Docs folders. |
| POST projects/:project_id/folders | Creates a new folder. |
| POST projects/:project_id/folders/:folder_id/relationships/refs | Creates a custom relationship between a folder and another resource within the data domain service (folder, item, or version). |
Items
Items represent the data contained by a project and can have many forms. Changes to items are tracked and all the versions are stored. The following are the supported endpoints and methods related to items.
| Endpoint | Description |
|---|---|
| GET projects/:project_id/items/:item_id | Returns a resource item by ID for any item within a given project. |
| GET projects/:project_id/items/:item_id/parent | Returns the “parent” folder for the given item. |
| GET projects/:project_id/items/:item_id/refs | Returns the resources (items, folders, and versions) that have a custom relationship with the given item_id. |
| GET projects/:project_id/items/:item_id/relationships/links | Returns a collection of links for the given item_id. |
| GET projects/:project_id/items/:item_id/relationships/refs | Returns the custom relationships that are associated with the given item_id. |
| GET projects/:project_id/items/:item_id/tip | Returns the “tip” version for the given item. |
| GET projects/:project_id/items/:item_id/versions | Returns versions for the given item. |
| PATCH projects/:project_id/items/:item_id | Updates the properties of the given item_id object. |
| POST projects/:project_id/items | Creates the first version of a file (item). |
| POST projects/:project_id/items/:item_id/relationships/refs | Creates a custom relationship between an item and another resource within the data domain service (folder, item, or version). |
Versions
Versions represent a specific state for an item. As the item changes, a new version is created. Versions can be queried to show the history of items.
| Endpoint | Description |
|---|---|
| GET projects/:project_id/versions/:version_id | Returns the version with the given version_id. |
| GET projects/:project_id/versions/:version_id/downloadFormats | Returns a collection of supported file formats this version could be converted to and downloaded as. |
| GET projects/:project_id/versions/:version_id/downloads | Returns a set of already available downloads for this version. |
| GET projects/:project_id/versions/:version_id/item | Returns the item the given version is associated with. |
| GET projects/:project_id/versions/:version_id/refs | Returns the resources (items, folders, and versions) that have a custom relationship with the given version_id. |
| GET projects/:project_id/versions/:version_id/relationships/links | Returns a collection of links for the given item_id-version_id object. |
| GET projects/:project_id/versions/:version_id/relationships/refs | Returns the custom relationships that are associated with the given version_id. |
| PATCH projects/:project_id/versions/:version_id | Updates the properties of the given version_id object. |
| POST projects/:project_id/versions | Creates new versions of a file (item), except for the first version of the item. |
| POST projects/:project_id/versions/:version_id/relationships/refs | Creates a custom relationship between a version and another resource within the data domain service (folder, item, or version). |
Buckets
| Endpoint | Description |
|---|---|
| POST buckets | Creates a bucket |
| GET buckets | Lists buckets |
| GET buckets/:bucketKey/details | Gets bucket details |
| POST buckets/:bucketKey/protect | Protects a bucket from accidental deletion |
| DELETE buckets/:bucketKey | Deletes a bucket |
Objects
Commands
Commands are used for performing complex operations on multiple resources rather than standard CRUD operations. For example, you can check whether a user has permission to delete specific versions, items, and folders. Commands are executed by sending requests in the body payload. Note that they share the same endpoint.
| Command | Description |
|---|---|
| CheckPermission | Checks which types of permissions a user has been granted to access specified versions, items, and folders for a given project. |
| ListRefs | Retrieves the custom relationships between specified versions of items and other folders, items, and versions in the data domain service. |
| ListItems | Retrieves metadata for specified items. For example, an item name, or the date it was created. |
| PublishModel | Publishes the latest version of a Collaboration for Revit (C4R) model to BIM 360 Docs. |
| PublishWithoutLinks | Publishes the latest version of a Collaboration for Revit (C4R) model without the links it contains to BIM 360 Docs. |
| GetPublishModelJob | Verifies whether a Collaboration for Revit (C4R) model needs to be published to BIM 360 Docs. |