Browse Content and Download Representations
This tutorial walks you through retrieving collections and content from a hub, listing content revisions, then listing revision representations and downloading a file using the Content Catalog API.
Before You Begin
- Register an app, and select the Content Catalog API.
- Acquire a 3-legged OAuth token with
data:readanddata:writescopes. - Verify that you have access to the relevant Forma hub.
- Obtain your hub ID using GET /project/v1/hubs (see Before You Begin).
Step 1: List Collections
Use your hub ID to list collections in the hub by calling GET Collections. The response includes each collection’s id, which you use in the next step.
Request
curl "https://api.aps.autodesk.com/content-catalog/v2/hubs/d6cf8c84-c25e-4534-ae5c-62e08480e751/collections" -X GET \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response
{
"results": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"hubId": "d6cf8c84-c25e-4534-ae5c-62e08480e751",
"name": "Doors and Windows",
"description": "Standard door and window families"
}
],
"pagination": {
"limit": 20,
"cursorState": null,
"nextUrl": null,
"nextCursorState": null
}
}
Pick the collection you want to use. Note its id (for example results[0].id) for Step 2.
Step 2: Get a Collection
Use your hub ID and the collection id from Step 1 to retrieve that collection by calling GET Collection.
Request
curl "https://api.aps.autodesk.com/content-catalog/v2/hubs/d6cf8c84-c25e-4534-ae5c-62e08480e751/collections/a1b2c3d4-e5f6-7890-abcd-ef1234567890" -X GET \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"hubId": "d6cf8c84-c25e-4534-ae5c-62e08480e751",
"name": "Doors and Windows",
"description": "Standard door and window families",
"permissions": {
"canRead": true,
"canDownloadInsert": true,
"canUpload": false,
"canEdit": false
},
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-03-20T14:45:00Z"
}
The response payload includes the collection details including permissions (permissions).
Step 3: List Content
Use the hub ID to retrieve all content items within the hub by calling GET Contents.
Request
curl "https://api.aps.autodesk.com/content-catalog/v2/hubs/d6cf8c84-c25e-4534-ae5c-62e08480e751/contents" -X GET \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response
{
"results": [
{
"id": "content-uuid-1",
"fileName": "Single_Door.rfa",
"fileType": "rfa",
"description": "Standard single door family",
"collectionIds": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
"currentRevision": {
"id": "revision-uuid-1",
"revisionNumber": 3,
"category": "Doors"
},
"createdAt": "2024-01-20T09:00:00Z",
"updatedAt": "2024-03-15T11:30:00Z"
}
],
"pagination": {
"cursorState": "eyJsYXN0S2V5IjoiY29udGVudC11dWlkLTEifQ==",
"limit": 50
}
}
The response payload includes the content item ID (results[0].id) and, when present, a current revision summary (results[0].currentRevision). Use the content ID in Step 5 to list all revisions; use a revision id from that list (or from currentRevision) when you list representations in Step 6.
Step 4: Filter Content
You can filter content by collection using the filter[collectionId] query parameter.
Request
curl "https://api.aps.autodesk.com/content-catalog/v2/hubs/d6cf8c84-c25e-4534-ae5c-62e08480e751/contents?filter[collectionId]=a1b2c3d4-e5f6-7890-abcd-ef1234567890" -X GET \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response
{
"results": [
{
"id": "content-uuid-1",
"fileName": "Single_Door.rfa",
"fileType": "rfa",
"collectionIds": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
"currentRevision": {
"id": "revision-uuid-1",
"revisionNumber": 3
}
}
],
"pagination": {
"cursorState": null,
"limit": 50
}
}
The filtered response includes only content items belonging to the specified collection.
Step 5: List Content Revisions
For a given content item, list every revision the catalog knows about by calling GET Revisions on /v2/hubs/{hubId}/contents/{contentId}/revisions. The response is paginated: use optional query parameters limit (default 20) and cursorState (from a previous response) to walk additional pages. You can send an optional Region header (US, EMEA, or AUS) to route the request; it defaults to US when omitted.
Use the hub ID and a content id from Step 3 or Step 4 (for example results[0].id).
Request
curl "https://api.aps.autodesk.com/content-catalog/v2/hubs/d6cf8c84-c25e-4534-ae5c-62e08480e751/contents/content-uuid-1/revisions" -X GET \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response
{
"results": [
{
"id": "revision-uuid-1",
"revisionNumber": 3,
"designProgram": "REVIT_2026",
"productVersions": ["2024", "2025"],
"category": "Doors",
"notes": "Updated family parameters",
"createdAt": "2024-03-15T11:30:00Z",
"updatedAt": "2024-03-18T14:22:09Z"
},
{
"id": "revision-uuid-0",
"revisionNumber": 2,
"designProgram": "REVIT_2025",
"productVersions": ["2023"],
"category": "Doors",
"createdAt": "2024-01-20T09:00:00Z",
"updatedAt": "2024-02-10T16:05:00Z"
}
],
"pagination": {
"limit": 20,
"cursorState": null,
"nextUrl": null,
"nextCursorState": null
}
}
Note each revision’s id (for example results[0].id). You need a revision ID for Step 6.
Step 6: List Representations
Each revision can have multiple representations, typically corresponding to different product versions (e.g., Revit 2023, Revit 2024). Use the hub ID, content ID, and revision ID from Step 5 to list available representations by calling GET Representations.
Request
curl "https://api.aps.autodesk.com/content-catalog/v2/hubs/d6cf8c84-c25e-4534-ae5c-62e08480e751/contents/content-uuid-1/revisions/revision-uuid-1/representations" -X GET \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response
{
"results": [
{
"id": "rep-uuid-2024",
"productVersion": "2024",
"createdAt": "2024-03-18T14:22:09.103Z",
"updatedAt": "2025-06-11T09:15:33.442Z",
"createdBy": "jdoe@example.com",
"updatedBy": "architect@example.com"
},
{
"id": "rep-uuid-2023",
"productVersion": "2023",
"createdAt": "2023-11-02T11:08:51.667Z",
"updatedAt": "2024-09-30T16:40:12.905Z",
"createdBy": "jdoe@example.com",
"updatedBy": "jdoe@example.com"
}
]
}
The response payload includes the representation ID (results[0].id), and product version (results[0].productVersion).
Step 7: Get Download URL
Use the hub ID, content ID, revision ID, and representation ID from Step 6 (for example results[0].id) to obtain a pre-signed download URL. Call POST Download URL on /v2/hubs/{hubId}/contents/{contentId}/revisions/{revisionId}/representations/{representationId}:get-download-url. Specify the type query parameter to indicate which artifact you want to download.
Available types:
CONTENT- The primary content file (e.g., RFA family file)TYPE_CATALOG- The Revit content type catalog file (e.g., RFA family file name with the .txt extension)PREVIEW_IMAGE- Preview thumbnail image
Request
curl "https://api.aps.autodesk.com/content-catalog/v2/hubs/d6cf8c84-c25e-4534-ae5c-62e08480e751/contents/content-uuid-1/revisions/revision-uuid-1/representations/rep-uuid-2024:get-download-url?type=CONTENT" -X POST \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
Response
{
"url": "https://storage.autodesk.com/presigned-url-here",
"expiresAt": "2024-03-20T15:30:00Z"
}
The response payload includes a pre-signed URL (url) that can be used to download the file. Note that this URL is temporary and will expire at the time indicated by expiresAt.
Step 8: Download the File
Use the pre-signed URL from the previous step to download the file directly.
Request
curl -o "Single_Door.rfa" "https://storage.autodesk.com/presigned-url-here"
The file will be downloaded to your local system with the specified filename.
Congratulations! You have listed collections, retrieved collection and content details, listed revisions and representations, and downloaded a representation file from Content Catalog.
To download multiple representation files in one request, use Batch Download URLs (POST /v2/hubs/{hubId}/contents:batch-download-urls).