Search
GET /assets/search, keyword search across a connected DAM.
Keyword search across assets in the connected DAM. Results include metadata, thumbnail, and download URLs; no separate requests are needed to display previews. Search behavior, such as which fields a keyword matches, is defined by the DAM.
Providers expose their own filter facets beyond the documented parameters. The
available facets are returned as filters in the response and in provider info;
send the selected facet values as additional query parameters.
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
Query Parameters
The search term. When omitted or empty, providers that support it return an unfiltered listing.
Search only within the specified folder. Omit or send an empty string for a global search.
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
curl -X GET "https://example.com/assets/search?size=50&more=next_page_token&filters=file_type%3Ajpg&filters=category%3Amarketing&timeZone=Africa%2FTunis&dataLocale=de-DE&uiLocale=en"{
"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"
}
],
"folders": [
{
"id": "folder_12345",
"name": "Summer Campaign 2024",
"relatedAssetId": "asset_123"
}
],
"filters": [
{
"id": "file_type",
"name": "File Type",
"options": [
{
"id": "fileType:jpg",
"isActive": false,
"name": "JPG Images",
"count": 45
}
]
}
],
"more": "next_page_token",
"capabilities": {
"canAddAsset": true
},
"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"
}
}Reading the result
Results use the same envelope as folder browse: a paged list of assets plus the search facets the connection exposes. Render filters in the search UI and pass the chosen option ids back as the filters query parameter to narrow the next search; the same facets appear in Provider info. See Asset model for the field reference, Asset URLs to fetch each asset's URLs, and Pagination for the more cursor.
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 { assets, filters, more } = await tokens.withDamAuth('dropbox', (accessToken, damToken) =>
client.search({ accessToken, damToken, options: { query: 'logo' } }),
)curl "https://stage.ci-hub.com/api/v1/assets/search?query=logo" \
-H "Authorization: Bearer $CI_HUB_ACCESS_TOKEN" \
-H "provider-authorization: Bearer $DAM_PROVIDER_TOKEN"const url = new URL('https://stage.ci-hub.com/api/v1/assets/search')
url.searchParams.set('query', 'logo')
const response = await fetch(url, {
headers: {
Authorization: `Bearer ${ciHubAccessToken}`,
'provider-authorization': `Bearer ${damProviderToken}`,
},
})
if (!response.ok) {
const { error } = await response.json()
throw new Error(`${error.code}: ${error.message}`)
}
const { assets, filters, more } = await response.json()