Content
Asset versions
GET /assets/assetversions/{assetId}, version history for an asset.
Retrieves the version history for an asset. Providers without versioning answer 501, 404, or 400 depending on the integration. Treat any of them as "not supported here".
Authorization
CIHubAuth ProviderAuth AuthorizationBearer <token>
The CI-HUB JWT token obtained through authentication. Needs to be sent in the Authorization header.
In: header
provider-authorization<token>
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
assetId*string
Asset identifier.
Query Parameters
withMaster?boolean
Include the master version in the result.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/assets/assetversions/string"{
"id": "string",
"name": "string",
"versions": [
{
"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"
}
]
}{
"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"
}
}{
"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"
}
}Provider support
Versioning is provider-dependent: a DAM without it answers with an error rather than a list. Read Provider info to learn whether the connected provider supports versioning, and gate the affordance in your UI on that. Each version is an asset object (see Asset model) carrying its own downloadUrl; resolve and fetch it like any other (see Asset URLs).
Reading the result
The response wraps the version list with the asset's id and name: { id, name, versions }. Each entry in versions is a full asset object. Pass withMaster=true to include the current master version alongside the historical ones.
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 { id, name, versions } = await tokens.withDamAuth('dropbox', (accessToken, damToken) =>
client.getAssetVersions({ accessToken, damToken, assetId: 'asset-456' }),
)curl "https://stage.ci-hub.com/api/v1/assets/assetversions/asset-456" \
-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/assetversions/asset-456',
{
headers: {
Authorization: `Bearer ${ciHubAccessToken}`,
'provider-authorization': `Bearer ${damProviderToken}`,
},
}
)
if (!response.ok) {
const { error } = await response.json()
throw new Error(`${error.code}: ${error.message}`)
}
const { id, name, versions } = await response.json()