Autodesk Construction Cloud

AutodeskClient

A class for interacting with Autodesk Platform Services APIs:

Data Management API
BIM 360 API
Autodesk Construction Cloud API

Handles differences in API conventions and schema, building on top of the Autodesk API to provide specialist methods for data translation / exchange use cases.

https://aps.autodesk.com/developer/documentation

Attributes:

Name	Type	Description
`user_id`		Unique ID for the user tethered to the client. Used to scope delegated access.
`client_id`		Autodesk client ID. Defaults to environment variable `AUTODESK_CLIENT_ID`.
`access_token`		Three-legged OAuth token for calling Autodesk APIs.

init

__init__(user_id, access_token=None, client_id=os.getenv('AUTODESK_CLIENT_ID'))

Initialize the client.

Parameters:

Name	Type	Description	Default
`user_id`	`str`	Unique ID for the user. Used to obtain three-legged access token. .	required
`access_token`	`str`	Optionally pass an OAuth access token directly to the constructor.	`None`
`client_id`	`str`	Three-legged OAuth token for calling Autodesk APIs.	`getenv('AUTODESK_CLIENT_ID')`

build_tree

build_tree()

Constructs a hierarchical tree structure of hubs and their associated projects.

This method fetches all accessible hubs from the Autodesk Forge API and then retrieves all projects within each hub, organizing them into a nested tree structure suitable for display in UI components like tree views or dropdowns.

The tree structure follows a hub -> project hierarchy where each hub contains multiple projects as children nodes.

Returns:

Type Description

List[Dict[str, Any]]

A list of dictionaries representing the tree structure. Each hub dictionary contains:

'id' (str): The hub's unique identifier
'label' (str): The hub's display name
'type' (str): Always 'hub' for hub entries
'children' (list): List of project dictionaries, each containing:
- 'id' (str): The project's unique identifier
- 'label' (str): The project's display name
- 'type' (str): Always 'project' for project entries
- 'children' (list): Empty list (reserved for future expansion)

build_tree_project

build_tree_project(hub_id, project_id)

Constructs a hierarchical tree structure of folders and items within a specific project.

This method fetches the top-level contents of a project and recursively builds a complete tree structure that includes all nested folders and their contents. The resulting tree is suitable for displaying the project's file/folder hierarchy in UI components.

Parameters:

Name	Type	Description	Default
`hub_id`	`str`	The unique identifier of the hub containing the project	required
`project_id`	`str`	The unique identifier of the project to build the tree for	required

Returns:

Type	Description
`List[Dict[str, Any]]`	A list of dictionaries representing the project's folder tree structure. Each folder dictionary contains: 'id' (str): The folder's unique identifier 'label' (str): The folder's display name 'type' (str): Always 'folder' for folder entries 'children' (list): Nested list of subfolders and items within this folder

download_file_bytes

download_file_bytes(file_href)

Downloads a file from Autodesk Forge and returns its content as bytes.

This method handles the multi-step process required to download files from Autodesk Forge: 1. Fetches file metadata using the provided file reference URL 2. Extracts the storage download URL from the metadata 3. Cleans the URL by removing query parameters that may interfere with the download 4. Requests a signed S3 download URL from Autodesk's storage service 5. Downloads the actual file content using the signed URL

Parameters:

Name	Type	Description	Default
`file_href`	`str`	The file reference URL obtained from Autodesk Forge API, typically from item or version data	required

Returns:

Name	Type	Description
`bytes`	`bytes`	The raw file content as bytes, or None if the download fails

exchange_refresh_token

exchange_refresh_token()

Retrieve the user's refresh token and exchange for a three-legged OAuth access token.

get_document_versions

get_document_versions(project_id, item_id)

Retrieve all versions for a specific document item.

This method fetches all available versions of a document item using the Autodesk Data Management API. Versions represent different iterations or revisions of the same document.

Parameters:

Name	Type	Description	Default
`project_id`	`str`	The project ID in Data Management API format (no "b." prefix)	required
`item_id`	`str`	The unique identifier for the document item	required

Returns:

Type	Description
`List[Dict[str, Any]]`	List of document versions

get_folder_contents

get_folder_contents(hub_id, project_id, folder_id=None)

Retrieve the contents of a folder in an Autodesk project, or get top-level folders if no folder ID is specified.

Parameters:

Name	Type	Description	Default
`hub_id`	`str`	The hub ID where the project is located	required
`project_id`	`str`	The project ID in Data Management API format (no "b." prefix)	required
`folder_id`	`str`	The folder ID to get contents for. If None, returns top-level folders for the project	`None`

Returns:

Type	Description
`Dict[str, Any]`	A dictionary containing folder contents at the folder-level only (not nested folders)

get_folder_contents_recursive

get_folder_contents_recursive(hub_id, project_id, folder_id)

Recursively retrieve all contents of a folder and its subfolders in an Autodesk project.

Parameters:

Name	Type	Description	Default
`hub_id`	`str`	The hub ID where the project is located	required
`project_id`	`str`	The project ID in Data Management API format (no "b." prefix)	required
`folder_id`	`str`	The folder ID to recursively get contents for	required

Returns:

Type	Description
`Dict[str, Any]`	A list of dictionaries representing the folder structure, where each item contains: id: The item ID project_id: The project ID hub_id: The hub ID name: The display name of the item label: The display name of the item (duplicate of name) type: The item type ('folders' or 'items') children: List of child items (only present for folders) Additional fields from the original item data

get_folder_named_attributes

get_folder_named_attributes(project_id, folder_id=None, hub_id=None)

Retrieves all custom attribute definitions for a folder within a specified project.

Custom attributes are user-defined metadata fields that can be attached to folders and items in BIM 360 / ACC.

Parameters:

Name	Type	Description	Default
`project_id`	`str`	The project identifier from the Data Management API (with "b." prefix, which will be automatically removed)	required
`folder_id`	`str`	The folder identifier from the Data Management API. If not provided function will retrieve the naming standard for the root project folder.	`None`
`hub_id`	`str`	The unique identifier of the hub containing the project. Must be provided if folder_id is not provided	`None`

Returns:

Type	Description
`List[Dict[str, Any]]`	A list of dictionaries containing custom attribute definitions from the folders in the project. Each dictionary represents an attribute definition with properties like name, type, validation rules, etc.

get_folder_naming_standard

get_folder_naming_standard(hub_id, project_id, folder_id=None)

Retrieves the naming standard configuration from a BIM 360 / ACC project for the specified folder. Returns None if no naming standard is applied to the folder

Naming standards define rules and patterns for how files and folders should be named within a project to maintain consistency and organization.

Parameters:

Name	Type	Description	Default
`hub_id`	`str`	The unique identifier of the hub containing the project	required
`project_id`	`str`	The project identifier from the Data Management API (no "b." prefix).	required
`folder_id`	`str`	The folder identifier from the Data Management API. If not provided function will retrieve the naming standard for the root project folder	`None`

Returns:

Type	Description
`Dict[str, Any]`	A dictionary containing the naming standard configuration data, including rules, patterns, and validation criteria defined for the standard

get_hubs

get_hubs()

Retrieves all hubs accessible to the authenticated user from the Autodesk Forge API.

Makes a GET request to the Autodesk Project API to fetch hub information. Hubs represent the highest level in the Autodesk data hierarchy and typically correspond to accounts or organizations that contain projects and folders.

Returns:

Type	Description
`Dict[str, Any]`	JSON response containing hub data from the API, including hub IDs, names, and other metadata. The exact structure depends on the Autodesk API response format.

get_naming_standard

get_naming_standard(project_id, naming_standard_id)

Retrieves a specific naming standard configuration from a BIM 360 / ACC project.

This method fetches the details of a naming standard by its ID from the specified project using the BIM 360 Docs API. Naming standards define rules and patterns for how files and folders should be named within a project to maintain consistency and organization.

Parameters:

Name	Type	Description	Default
`project_id`	`str`	The project identifier from the Data Management API (with "b." prefix, which will be automatically removed)	required
`naming_standard_id`	`str`	The unique identifier of the naming standard to retrieve	required

Returns:

Type	Description
`Dict[str, Any]`	A dictionary containing the naming standard configuration data, including rules, patterns, and validation criteria defined for the standard

get_projects

get_projects(hub_id)

Retrieves all projects within a specified hub from the Autodesk Forge API.

Makes a GET request to the Autodesk Project API to fetch project information for a given hub. Projects are containers within hubs that hold folders, items, and other project-related data.

Parameters:

Name	Type	Description	Default
`hub_id`	`str`	The unique identifier of the hub to retrieve projects from. This should be obtained from a previous call to get_hubs().	required

Returns:

Type	Description
`Dict[str, Any]`	JSON response containing project data from the API, including project IDs, names, and other metadata. The exact structure depends on the Autodesk API response format.

get_signed_url

get_signed_url(file_href, minutes=60)

Fetches a signed URL for downloading a file from an AWS S3 bucket.

This function retrieves file details using the provided file reference URL (file_href) and an access token for authorization. It then constructs a signed URL for the file by stripping unnecessary query parameters, appending a specific download endpoint, and extracting the signed URL from the download response.

Parameters:

Name	Type	Description	Default
`file_href`	`str`	The URL pointing to the file reference details in the storage system	required
`minutes`	`int`	Time duration for validity of URL. Maximum 60 minutes.	`60`

Returns:

Type	Description
`str`	The signed URL for downloading the file.

patch_version_attributes

patch_version_attributes(project_id, version_id, attributes)

Update attributes for a document version using the Data Management API.

This method updates version-level attributes for a specific document version using the Autodesk Data Management API's PATCH endpoint.

Parameters:

Name	Type	Description	Default
`project_id`	`str`	The project ID in Data Management API format (no "b." prefix)	required
`version_id`	`str`	The unique identifier for the document version.	required
`attributes`	`Dict[str, Any]`	Dict of attribute objects to update.	required

Returns:

Type	Description
`Dict[str, Any]`	A dictionary containing the updated document version

post_version_custom_attributes

post_version_custom_attributes(project_id, version_id, attributes)

Update custom attributes for a document version in BIM 360.

This method performs a batch update of custom attributes for a specific document version using the BIM 360 Docs API. It converts the Data Management API project ID format to the BIM 360 API format by removing the "b." prefix.

Parameters:

Name	Type	Description	Default
`project_id`	`str`	The project ID from either Data Management API or BIM 360 API. "b." prefix will be removed	required
`version_id`	`str`	The unique identifier for the document version	required
`attributes`	`List[Dict[str, Any]]`	List of custom attribute objects to update. Each dictionary should contain attribute data	required

Returns:

Type	Description
`Dict[str, Any]`	A dictionary containing the updated custom attributes for the document

upload_file_bytes

upload_file_bytes(project_id, folder_id, file_name, file_bytes)

Upload file byte content to an Autodesk project folder. If a file with file_name already exists then will append file_bytes as a new item version.

Parameters:

Name	Type	Description	Default
`project_id`	`str`	The project ID in Data Management API format (no "b." prefix)	required
`folder_id`	`str`	The folder ID	required
`file_name`	`str`	The name of the file	required
`file_bytes`	`bytes`	Contents of the file	required

Returns:

Type Description

Dict[str, Any]

A dictionary containing upload information with the following keys:

object_id: The storage object ID
bucket: The bucket key
object_key: The object key
upload_status: Status of the upload (should be 'success')
action: Type of action performed ('new file' or 'new version')
version_id: The ID of the created version
version_number: The version number assigned
existing_item_id: The item ID if file already existed, None otherwise

Raises:

Type	Description
`Exception`	If folder information cannot be retrieved
`Exception`	If storage location creation fails
`Exception`	If signed URL generation fails
`Exception`	If file upload to signed URL fails
`Exception`	If upload validation fails
`Exception`	If version/item creation fails

AutodeskDAClient

A client for interacting with Autodesk's Design Automation service via the Design Automation API.

https://aps.autodesk.com/en/docs/design-automation/v3/developers_guide/overview/

Attributes:

Name	Type	Description
`access_token`		Two-legged OAuth token for calling the Design Automation API.

init

__init__()

Initialize the client.

encode_to_base64

encode_to_base64(input_string)

Encodes a given string into Base64.

Parameters:

Name	Type	Description	Default
`input_string`	`str`	The string to encode	required

Returns:

Type	Description
`str`	The Base64 encoded string

get_bearer_token

get_bearer_token()

Obtain a two-legged OAuth access token with sufficent scope to read and write work items.

Returns:

Type	Description
`str`	Access token

queue_work_item_dwg

queue_work_item_dwg(download_url, callback_url)

Queues a work item to execute a Design Automation activity. The activity opens an Autdoesk AutoCAD drawing (DWG) and converts the sheets to PDF.

Parameters:

Name	Type	Description	Default
`download_url`	`str`	A signed or public URL where the Design Automation service can GET the AutoCAD file	required
`callback_url`	`str`	A signed or public URL for the Design Automation service to POST the PDF	required

Returns:

Type	Description
`Callable`	Polls the Design Automation service until the work item terminates

queue_work_item_inventor

queue_work_item_inventor(input_url, output_metadata_url, output_thumbnail_url)

Queues a work item to execute a Design Automation activity. The activity opens an Autdoesk Inventor part (IPT), assembly (IAM) or drawing (IDW) file and generates:

A JSON metadata file describing key file properties
A thumbnail image in isometric projection

Parameters:

Name	Type	Description	Default
`input_url`	`str`	A signed or public URL where the Design Automation service can GET the Inventor file	required
`output_metadata_url`	`str`	A signed or public URL for the Design Automation service to POST metadata JSON	required
`output_thumbnail_url`	`str`	A signed or public URL for the Design Automation service to POST thumbnail image	required

Returns:

Type	Description
`Callable`	Polls the Design Automation service until the work item terminates