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:
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
collections1-to-many | Collections belonging to this hub |
content1-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
hub1-to-1 | Parent hub for this collection |
contentmany-to-many | Content items within this collection |
groupsmany-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
hub1-to-1 | Parent hub for this content |
collectionsmany-to-many | Collections containing this content |
revisions1-to-many | Revision history for this content |
tagsmany-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
content1-to-1 | Parent content for this revision |
representations1-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
revision1-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 (
groupIdequal tohubId) represents hub administrators; its membership is derived from Autodesk Forma and cannot be modified through these APIs except forpinnedCollections - 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
hub1-to-1 | Parent hub for this group |
users1-to-many | Group membership records (see User Group Users) |
collectionsmany-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
userIdin API requests must be an Autodesk Forma account-user UUID- Membership type (
USER,ROLE, orCOMPANY) 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
group1-to-1 | Parent user group for this membership |
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.