Content
Search by image
POST /assets/search, find visually similar assets from a reference image.
Similarity search using a reference image. Provide either Base64-encoded image data or an HTTP/HTTPS URL to the image. Not supported by all providers; check the provider capabilities in the providers listing.
Providers without this capability 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
Query Parameters
size?string
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.
more?string
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.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/assets/search?size=50&more=next_page_token" \ -H "Content-Type: application/json" \ -d '{ "dataBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAOEAA..." }'{
"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"
}
}{
"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"
}
}Reference image
The request body takes either a base64 data URI or an http(s) URL, which CI HUB fetches and converts before searching. The simplest reference is the downloadUrl of an asset already in a result, which lets a user search for more like a given asset. Results use the same envelope as keyword search; see Asset model for the field reference and Asset URLs to fetch each asset's URLs.
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, more } = await tokens.withDamAuth('dropbox', (accessToken, damToken) =>
client.searchSimilar({ accessToken, damToken, dataBase64: referenceImageUrl }),
)curl -X POST "https://stage.ci-hub.com/api/v1/assets/search" \
-H "Authorization: Bearer $CI_HUB_ACCESS_TOKEN" \
-H "provider-authorization: Bearer $DAM_PROVIDER_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "dataBase64": "https://example.com/reference.png" }'const response = await fetch(
'https://stage.ci-hub.com/api/v1/assets/search',
{
method: 'POST',
headers: {
Authorization: `Bearer ${ciHubAccessToken}`,
'provider-authorization': `Bearer ${damProviderToken}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ dataBase64: referenceImageUrl }),
}
)
if (!response.ok) {
const { error } = await response.json()
throw new Error(`${error.code}: ${error.message}`)
}
const { assets, more } = await response.json()From a local file
To search with bytes you hold locally, build a base64 data URI and pass it as dataBase64 instead of a URL:
import { readFile } from 'node:fs/promises'
const bytes = await readFile('reference.png')
const dataUri = `data:image/png;base64,${bytes.toString('base64')}`
// POST { dataBase64: dataUri } exactly as in the example above