Request

Response

    Field Guide

    This section describes the key concepts and terms used in the Content Catalog API.

    Overview

    The Content Catalog API organizes content within a Hub (a Forma account where Content Catalog is activated). Content is organized using Collections, which provide permission-controlled grouping. Each piece of Content can have multiple Revisions, and each revision can have multiple Representations (file versions for different product versions).

    The diagram below depicts the hierarchical structure:

    ../../../_images/Field_Guide_Diagram.png

    In the following sections, we explain each of these concepts.

    Organizational Structure:

    • Hub
    • Collection
    • Content
    • Revision
    • Representation

    Supporting entities:

    • User Groups
    • User Group Users
    • Tags
    • Saved Search Groups
    • Saved Searches

    Hub

    A Hub represents a Forma account and serves as the top-level organizational boundary for all content.

    Key Characteristics:

    • Hub ID corresponds to the Forma Account ID (UUID format)
    • Forma is the source of truth for account metadata (name, region)
    • Hub-specific settings (such as tag permissions) are managed by Content Catalog
    id
    string: UUID
    The hub ID (matches Forma Account ID)
    name
    string
    The hub name (from Forma)
    region
    string
    The region: US, EMEA, or AUS
    imageUrl
    string
    URL of the hub’s logo image
    isPublisher
    boolean
    Whether this hub can publish content

    Relationships

    collections
    1-to-many
    Collections belonging to this hub
    content
    1-to-many
    Content items within this hub

    Collection

    A Collection is a permission-controlled grouping mechanism for organizing content. Collections enable secure sharing and collaboration by controlling who can view, download, or modify the content within.

    Key Characteristics:

    • Hub-scoped: Each collection belongs to a specific hub
    • Access control through group assignments
    • Content can belong to multiple collections
    • Hub administrators can remove a collection thumbnail without deleting the collection (DELETE .../collections/{collectionId}?type=PREVIEW_IMAGE)
    id
    string: UUID
    The collection ID
    hubId
    string: UUID
    The hub this collection belongs to
    name
    string
    Display name for the collection
    description
    string
    Detailed description of the collection
    permissions
    object
    Permission flags (canRead, canDownloadInsert, canUpload, canEdit)
    createdBy
    string
    User who created the collection
    createdAt
    datetime: ISO 8601
    Timestamp when the collection was created
    updatedBy
    string
    User who last updated the collection
    updatedAt
    datetime: ISO 8601
    Timestamp when the collection was last updated

    Relationships

    hub
    1-to-1
    Parent hub for this collection
    content
    many-to-many
    Content items within this collection
    groups
    many-to-many
    Groups with permissions on this collection

    Content

    Content is the core entity representing a digital design asset within Content Catalog. It aggregates metadata from files, revisions, and formats, including information such as Revit parameters and family data.

    Supported Content Types:

    • Revit families (RFA)
    • Materials
    • Fill patterns
    • System types
    • Schedules
    • Templates
    • Other CAD/BIM assets
    id
    string: UUID
    The content ID
    hubId
    string: UUID
    The hub this content belongs to
    fileName
    string
    Name of the content file
    fileType
    string
    Type of the file
    description
    string
    Description of the content
    comments
    string
    Additional comments
    collectionIds
    array: UUID
    Collections this content belongs to
    tagIds
    array: UUID
    Tags associated with this content
    currentRevision
    object
    The current (latest) revision
    createdBy
    string
    User who created the content
    createdAt
    datetime: ISO 8601
    Timestamp when the content was created
    updatedBy
    string
    User who last updated the content
    updatedAt
    datetime: ISO 8601
    Timestamp when the content was last updated

    Relationships

    hub
    1-to-1
    Parent hub for this content
    collections
    many-to-many
    Collections containing this content
    revisions
    1-to-many
    Revision history for this content
    tags
    many-to-many
    Tags associated with this content

    Revision

    A Revision represents a specific version of content. When content is updated, a new revision is created to maintain version history.

    id
    string: UUID
    The revision ID
    revisionNumber
    integer
    Sequential revision number
    category
    string
    Content category
    product
    string
    Source product (e.g., Revit)
    parameters
    array: object
    Revit parameters and metadata
    notes
    string
    Revision notes
    createdBy
    string
    User who created the revision
    createdAt
    datetime: ISO 8601
    Timestamp when the revision was created
    updatedBy
    string
    User who last updated the revision
    updatedAt
    datetime: ISO 8601
    Timestamp when the revision was last updated

    Relationships

    content
    1-to-1
    Parent content for this revision
    representations
    1-to-many
    File representations for this revision

    Representation

    A Representation is a specific file version of a revision, typically corresponding to different product versions (e.g., Revit 2023, Revit 2024).

    id
    string: UUID
    The representation ID
    productVersion
    string
    Product version (e.g., “2024”)
    fileSize
    number
    Size of the file in bytes
    availableAttachments
    array
    Available attachment types (TYPE_CATALOG, PREVIEW_IMAGE)
    createdBy
    string
    User who created the representation
    createdAt
    datetime: ISO 8601
    Timestamp when the representation was created
    updatedBy
    string
    User who last updated the representation
    updatedAt
    datetime: ISO 8601
    Timestamp when the representation was last updated

    Relationships

    revision
    1-to-1
    Parent revision for this representation

    User Groups

    A User Group is a hub-scoped permission group that controls access to collections and other Content Catalog resources. Groups can be assigned read, edit, upload, and download permissions on collections.

    Key Characteristics:

    • Hub-scoped: Each user group belongs to a specific hub
    • The hub’s admin group (groupId equal to hubId) represents hub administrators; its membership is derived from Autodesk Forma and cannot be modified through these APIs except for pinnedCollections
    • Custom groups can be created, updated, and deleted through the API
    id
    string: UUID
    The user group ID
    hubId
    string: UUID
    The hub this group belongs to
    name
    string
    Display name for the group
    isAdminGroup
    boolean
    Whether this is the hub’s admin group (group ID equals the hub ID)
    pinnedCollections
    array: UUID
    Collection IDs pinned to this group (optional)
    createdBy
    string
    User who created the group
    createdAt
    datetime: ISO 8601
    Timestamp when the group was created
    updatedBy
    string
    User who last updated the group
    updatedAt
    datetime: ISO 8601
    Timestamp when the group was last updated

    Relationships

    hub
    1-to-1
    Parent hub for this group
    users
    1-to-many
    Group membership records (see User Group Users)
    collections
    many-to-many
    Collections this group has permissions on

    User Group Users

    A User Group User represents a membership record linking a user, role, or company to a user group. Membership determines which users inherit the group’s collection permissions.

    Key Characteristics:

    • Scoped to a specific user group within a hub
    • userId in API requests must be an Autodesk Forma account-user UUID
    • Membership type (USER, ROLE, or COMPANY) determines how the member is validated
    • The hub’s admin group membership is derived from Autodesk Forma and cannot be added or removed through these APIs
    userId
    string: UUID
    Autodesk Forma account-user UUID of the member
    userGroupId
    string: UUID
    The group this membership belongs to
    hubId
    string: UUID
    The hub this membership belongs to
    membershipType
    string
    Type of membership: USER, ROLE, or COMPANY

    Relationships

    group
    1-to-1
    Parent user group for this membership

    Tags

    Tags are hub-scoped labels used to organize and filter content. Hub administrators and authorized users can create tags through the API; tags can be assigned to content items via tagIds.

    Tags created or updated through the API may not appear immediately in the legacy Content Catalog web UI. Refresh the page or sign out and back in to trigger a resync. Newer Content Catalog experiences read tag data directly from the API and reflect changes in near real time.

    Saved Search Groups

    Saved search groups organize saved searches within a hub. Each group has a scope:

    • HUB — Visible to all hub members. Only hub administrators can create, update, or delete hub-scoped groups.
    • PERSONAL — Visible only to the user who created the group. Only that owner can manage a personal group; hub administrators cannot see or modify another user’s personal groups.

    Saved Searches

    Saved searches store reusable search filters (for example collection, tag, or text criteria) within a hub. Like saved search groups, each saved search has a scope:

    • HUB — Shared with all hub members. Only hub administrators can create, update, or delete hub-scoped saved searches.
    • PERSONAL — Private to the creator. Only the owner can manage a personal saved search.