Folder browse
GET /assets/folder/{folderId}, list subfolders and assets at a folder.
Browses folder contents. Returns subfolders and assets with metadata and thumbnail
URLs. Navigation is hierarchical: start from the root folder and traverse by ID.
Asset pagination uses the more cursor; folders are not paged by it.
Authorization
CIHubAuth ProviderAuth The CI-HUB JWT token obtained through authentication. Needs to be sent in the Authorization header.
In: header
Provider-specific authentication token for accessing the provider's services. Needs to be sent in the provider-authorization header with the Bearer prefix.
In: header
Path Parameters
Folder identifier. Pass root to start at the connected provider's root folder, then traverse by the id of each subfolder.
Query Parameters
Number of assets to return per page. The maximum value is also specified by the provider in the server configuration. The smaller of the two values will be used.
Token for continuing a previous request on the next page. Should be set to the value of more as received by the previous call to this endpoint.
List of filters to apply to the search. An array of option ids is expected here. You can optain them in the response of the previous call to this endpoint inside each filter in the filters property.
Only used for AdmiralCloud and Asana. Timezone for date/time formatting. It expects a valid timezone based on the Intl.DateTimeFormat library. Use Intl.DateTimeFormat().resolvedOptions().timeZone to get the timezone of the user. See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/resolvedOptions#timezone for more information.
If the provider supports data localization, this is the locale for the content of the data (e.g., values of metadata fields). You can find the supported data locales of the provider in the response of the /system/providerInfo route. Send the id of the locale here.
Locale for user interface elements. For example, labels of metadata fields. Only the locales in the enum are supported. When omitted, providers fall back to en.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/assets/folder/root?size=50&more=next_page_token&filters=file_type%3Ajpg&filters=category%3Amarketing&timeZone=Africa%2FTunis&dataLocale=de-DE&uiLocale=en"{
"id": "folder_12345",
"name": "Marketing Assets 2024",
"more": "next_page_token",
"capabilities": {
"canDeleteFolder": true,
"canAddFolder": true,
"canAddAsset": true,
"canRenameFolder": true
},
"folders": [
{
"id": "folder_12345",
"name": "Summer Campaign 2024",
"relatedAssetId": "asset_123"
}
],
"assets": [
{
"id": "asset_12345",
"name": "product-photo.jpg",
"parentPath": "/Marketing/2024/Campaign",
"fileSize": 2048576,
"xSizePx": 1920,
"ySizePx": 1080,
"created": 1704067200000,
"modified": 1704153600000,
"mimeType": "image/jpeg",
"version": 1,
"versionComment": "Updated product shot with new background",
"downloadHashMd5": "a1b2c3d4e5f6...",
"downloadHashSha1": "a1b2c3d4e5f6...",
"downloadHashSha256Split4MB": "a1b2c3d4e5f6...",
"downloadHashSha256First16MB": "a1b2c3d4e5f6...",
"downloadHashSha256": "a1b2c3d4e5f6...",
"downloadHashSha512": "a1b2c3d4e5f6...",
"downloadHashFileAttributes": "a1b2c3d4e5f6...",
"downloadHashCrc32": "1a2b3c4d",
"thumbnailUrl": "https://api.example.com/assets/123/thumbnail",
"downloadUrl": "https://api.example.com/assets/123/download",
"assetDetailsExternalUrl": "https://external-system.com/assets/123",
"lockedBy": "user_456",
"capabilities": {
"canDeleteAsset": true,
"canUpdateAsset": true,
"canLockAsset": true,
"canUnlockAsset": true,
"canRenameAsset": true,
"uploadExtensions": [
"string"
]
},
"type": "string",
"conversions": [
{
"id": "conv_thumb",
"name": "Thumbnail",
"url": "https://api.example.com/assets/123/conversions/thumb",
"extension": "jpg",
"disabled": false,
"description": "Small thumbnail for preview"
}
],
"displayVersion": 2,
"title": "Product Photography - Summer Collection",
"caption": "Professional product shot showcasing the new summer collection",
"copyright": "© 2024 Company Name. All rights reserved.",
"termsOfUse": "For internal marketing use only",
"instructions": "Use with proper attribution and company branding",
"colorSpace": "sRGB",
"releasedBy": "designer@company.com",
"releasedDate": 1757449091674,
"released": "approved",
"keywords": [
"product",
"summer",
"collection",
"photography"
],
"categories": [
"marketing",
"product",
"seasonal"
],
"states": [
"approved",
"published",
"featured"
],
"exif": {
"cameraModel": "Canon EOS R5",
"orientation": "vertical",
"exposureTime": 12,
"apertureValue": "f/2.8",
"isoSpeedRatings": "string",
"width": 1920,
"height": 1080,
"resolution": "string",
"dateTimeOriginal": 1714857600000
},
"iptc": {
"headline": "Summer Collection Launch",
"caption": "Professional product photography for the new summer collection",
"captionWriter": "Cool Photographer",
"instructions": "For editorial use only",
"copyrightNotice": "© 2024 Company Name",
"credit": "John Doe Photography",
"city": "New York",
"provinceState": "NY",
"countryName": "United States"
},
"xmp": {
"headline": "Summer Collection Launch",
"credit": "John Doe Photography",
"city": "New York",
"provinceState": "NY",
"countryName": "United States",
"originalDocumentId": "string",
"documentId": "string",
"instanceId": "string",
"iccProfileDescription": "string"
},
"values": [
{
"id": "string",
"type": "TEXT",
"value": "string",
"name": "string",
"i18nName": {
"en": "Name",
"de": "Name",
"fr": "Nom"
}
}
],
"relatedFolderId": "folder_123",
"masterId": "123"
}
],
"filters": [
{
"id": "file_type",
"name": "File Type",
"options": [
{
"id": "fileType:jpg",
"isActive": false,
"name": "JPG Images",
"count": 45
}
]
}
],
"totalAssetsCount": 150
}{
"message": "Error",
"details": "POST /api/v1/auth/exchangeToken failed: SDK authentication token is invalid",
"errorCode": "cihub-sdk-token-invalid",
"error": {
"code": "integration-forbidden",
"source": "cihub",
"status": 400,
"message": "Access denied by the integration",
"details": "403 Forbidden - insufficient_permissions",
"provider": "bynder"
}
}{
"message": "Error",
"details": "POST /api/v1/auth/exchangeToken failed: SDK authentication token is invalid",
"errorCode": "cihub-sdk-token-invalid",
"error": {
"code": "integration-forbidden",
"source": "cihub",
"status": 400,
"message": "Access denied by the integration",
"details": "403 Forbidden - insufficient_permissions",
"provider": "bynder"
}
}{
"message": "Error",
"details": "POST /api/v1/auth/exchangeToken failed: SDK authentication token is invalid",
"errorCode": "cihub-sdk-token-invalid",
"error": {
"code": "integration-forbidden",
"source": "cihub",
"status": 400,
"message": "Access denied by the integration",
"details": "403 Forbidden - insufficient_permissions",
"provider": "bynder"
}
}{
"message": "Error",
"details": "POST /api/v1/auth/exchangeToken failed: SDK authentication token is invalid",
"errorCode": "cihub-sdk-token-invalid",
"error": {
"code": "integration-forbidden",
"source": "cihub",
"status": 400,
"message": "Access denied by the integration",
"details": "403 Forbidden - insufficient_permissions",
"provider": "bynder"
}
}{
"message": "Error",
"details": "POST /api/v1/auth/exchangeToken failed: SDK authentication token is invalid",
"errorCode": "cihub-sdk-token-invalid",
"error": {
"code": "integration-forbidden",
"source": "cihub",
"status": 400,
"message": "Access denied by the integration",
"details": "403 Forbidden - insufficient_permissions",
"provider": "bynder"
}
}Reading the result
folders arrives in full on the first page; more pages through assets only. Read every subfolder from the first response, then keep pulling assets until more is absent (see Pagination). Each asset carries its own thumbnailUrl and downloadUrl; resolve and fetch them as described in Asset URLs. Folder IDs are opaque and can contain slashes, so pass them through as received; start a traversal from root.
Example
import { CiHubAccessClient, TokenManager } from '@ci-hub/access-sdk'
const client = new CiHubAccessClient({ baseUrl: 'https://stage.ci-hub.com/api/v1' })
const tokens = new TokenManager(client) // seeded during authentication
const { folders, assets, more } = await tokens.withDamAuth('dropbox', (accessToken, damToken) =>
client.getFolder({ accessToken, damToken, folderId: 'root' }),
)curl "https://stage.ci-hub.com/api/v1/assets/folder/root" \
-H "Authorization: Bearer $CI_HUB_ACCESS_TOKEN" \
-H "provider-authorization: Bearer $DAM_PROVIDER_TOKEN"const response = await fetch(
'https://stage.ci-hub.com/api/v1/assets/folder/root',
{
headers: {
Authorization: `Bearer ${ciHubAccessToken}`,
'provider-authorization': `Bearer ${damProviderToken}`,
},
}
)
if (!response.ok) {
const { error } = await response.json()
throw new Error(`${error.code}: ${error.message}`)
}
const { folders, assets, more } = await response.json()