Request

Response

    ACC Sheets API Field Guide

    This field guide describes the components of the Autodesk Construction Cloud Sheets service and shows how they work together. It also provides key concepts to help you successfully use the ACC Sheets API.

    For more information about Sheets features, please refer to Sheets Help.

    Sheets

    Sheet is the primary component of ACC Sheets service. One sheet represents one view of a document, e.g. one page of PDF, or one 2D view of RVT. Currently, the Sheets API only supports uploading PDF files and does not support associating them with collections.

    This table shows the standard attributes that define each sheet:

    NameRequired Value?Description
    ID Yes The ID of the sheet. Should be unique within a project. All operations use ID to confirm the scope.
    Number Yes The number of the sheet, a human-readable identifier. Shows as primary description of Number column in ACC Sheets UI.

    The number is automatically extracted from the sheet’s title block and can be updated on demand.
    Title Yes The title of the sheet. Shows as secondary description of Number column in ACC Sheets UI.

    The title is automatically extracted from the sheet title block and can be updated on demand.
    Tags Yes A list of user defined tags of the sheet.
    Version Set ID Yes The ID of the version set that the sheet belongs to.
    Viewable No The URN and view GUID that can be used to load the view in Viewer.

    Version Sets

    Version set is the collection of sheets. One version set can have multiple sheets, but the sheet number must be unique in each version set. Deleting version set will also delete all the sheets within the version set.

    This table shows the standard attributes that define each version set:

    NameRequired Value?Description
    ID Yes The ID of the version set. Should be unique within a project. All operations use ID to confirm the scope.
    Name Yes The name of the version set, a human-readable identifier. Should be unique within the project.
    Issuance Date Yes Represents the date that the sheets are issued to other project members. Determines attribute current of sheets, please refer to Current Sheets section.

    Uploads

    An upload represents the process of uploading files, extracting and reviewing individual sheets from the files, and publishing them to ACC Sheets.

    This table shows the standard attributes that define each upload:

    NameRequired Value?Description
    ID Yes The ID of the upload. Should be unique within a project. All operations use ID to confirm the scope.
    Version Set ID Yes The ID of the version set that will contain all the sheets published by the upload.
    Status Yes The status of the upload, changes according to API call and processing status. Possible values: PENDING, PROCESSING, IN_REVIEW, FAILED, UPDATING_VERSION_SET, PUBLISHING, PUBLISHED.

    A typical workflow of upload will be:

    ../../../_images/sheets-upload-workflow.jpg

    In ACC Files, all storages share one OSS bucket. But in ACC Sheets, each project has its own OSS bucket. It is recommended to extract bucket key from storage URN every time before you call OSS APIs.

    ../../../_images/sheets-bucket.png

    Please refer to Upload Files to ACC Sheets tutorial to see a detailed example of upload.

    Review Sheets

    Review sheets are the objects temporarily created by upload for review before publishing. The information of review sheets is extracted from the uploaded files, and can be updated by PATCH review-sheets. Each review sheet will be converted to one sheet in upload publishing process. The new sheet will have the attributes identical to the review sheet. The review sheet will then be deleted and become no longer accessible.

    The review sheets will be entirely deleted when related upload has already been published.

    This table shows the standard attributes that define each review sheet:

    NameRequired Value?Description
    ID Yes The ID of the review sheet.
    Number Yes The number of the review sheet, will be inherit by the published sheet.
    Title Yes The title of the review sheet, will be inherit by the published sheet.
    Tags Yes A list of user defined tags of the review sheet, will be inherit by the published sheet.
    Deleted Yes The deleted status of the review sheet. Review sheets marked as deleted=true will not be published.
    Processing State Yes The processing status of the review sheet. Possible values: PROCESSING, ROTATING, AUDITING, READY, FAILED, PUBLISHING.

    Current Sheets

    As mentioned in Version Sets section, Sheet number should be unique in one version set, but you can use same sheet number in different version sets. To avoid confusion, the ACC Sheets service orders the sheets with same number by the issuance dates of their version sets, and only shows the sheet in the last. In this case, the last sheet is the current sheet.

    Sheet model has an attribute isCurrent to indicate whether a sheet is current.

    You can use query parameter currentOnly to specify whether you need all the sheets or only the current sheets in the API GET sheets.

    Deleting

    In the ACC Sheets API, deleting behaviors are different for different kinds of components.

    • Sheets: supports deleting and restoring, should use specific APIs.
    • Version Sets: supports only deleting.
    • Review Sheets: deleted is just a flag that indicates upload does not need to publish this review sheet. Call PATCH review-sheets to update the attribute deleted.

    Other components do not support deleting in this release.

    Export

    To export sheets, users must have, at a minimum, export permissions.

    Users can export sheets that include both standard markups and feature markups. Currently, the features supported are Issues and Photos. For more information on sheet markups, see the Sheets Markups Help.

    Below is a table showing the different types of markups that can be included during sheet export.

    TypeDescription
    Published standard markups Markups visible to all project members.
    Unpublished standard markups Markups visible only to their creator.
    Added markup links Links added manually to a standard markup, including links to Sheets, Files, RFIs, Forms, Submittals, and Assets.
    Published issues markups Issues visible to anyone with the correct permission on your project.
    Unpublished issues markups Issues visible only to the issue markup creator and the assignee.
    Published photos markups Photos visible to anyone on your project. A subscription to Autodesk Build is required.
    Unpublished photos markups Photos visible only to the photo markup creator. A subscription to Autodesk Build is required.

    Collections

    A collection organizes sheets in the ACC Sheets module, enabling duplicate sheet numbers (e.g., A101, A102) across different collections within a project.

    A collection can include multiple sheets and version sets, but sheet numbers must be unique within each collection.

    Deleting a collection also deletes all its sheets and version sets.

    Currently, the Sheets API only supports querying collections.

    For more details about Sheets Collections, see the Help documentation.

    This table outlines the standard attributes that define each sheets collection:

    NameRequired Value?Description
    ID Yes The unique identifier for the collection within a project. Used to reference the collection in all operations.
    Name Yes A human-readable identifier for the collection. Displays as the primary description in the Name column of the ACC Sheets UI.

    Limitations

    The ACC Sheets API currently does not support the following features:

    • Importing PDFs or RVTs directly from the Files module of an ACC project. You can only upload PDFs from local storage, and collections are not supported for these uploads.
    • Rotating review sheets.
    • Managing sheet permissions or disciplines.
    • Managing markups.
    • Managing collections. The Sheets API only supports querying collections.
    • Managing version sets and sheets within collections.