Browse and search the collection.

Catalog resources

Relationship endpoints can require both resource scopes—for example, collection artworks require collections:read and artworks:read.

Simple search

GET search works well for straightforward query-string integrations:

curl --get "https://collection.vieunite.com/v1/search" \
  -H "Authorization: Bearer $VIEUNITE_TENANT_TOKEN" \
  --data-urlencode "q=landscape" \
  --data-urlencode "types=artwork,collection" \
  --data-urlencode "orientation=landscape" \
  --data-urlencode "facets=medium,movement" \
  --data-urlencode "limit=24"

For artworks, orientation matches when at least one currently available version has the requested orientation. Multiple versions with the same orientation count once per artwork in that facet, while one artwork can appear in several orientation buckets. dimensions.pixel.orientation still describes the artwork record and is not the filter source. Collection orientation remains a single declared value.

Advanced search

Use POST search for structured filters, multiple sorts, facets and a field projection:

curl --request POST "https://collection.vieunite.com/v1/search" \
  -H "Authorization: Bearer $VIEUNITE_TENANT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "query": "coast",
  "types": ["artwork"],
  "filters": {
    "resource_type": "image",
    "orientation": "landscape",
    "medium": "oil on canvas",
    "quality_score": { "gte": 75 }
  },
  "facets": ["movement", "medium", "rights.license"],
  "sort": [
    { "field": "quality_score", "order": "desc" }
  ],
  "page": { "limit": 24 },
  "fields": [
    "id", "type", "name", "artist",
    "production.medium", "assets.thumbnail",
    "version", "updated_at"
  ]
}'

Consult GET /v1/capabilities for the current filter, facet, sort and asset-variant vocabulary rather than hard-coding an assumed catalogue.

Read artwork versions

available_versions contains each selectable composition and its safe thumbnail, source geometry and delivery geometry. Preserve the API order, treat key as opaque, and persist the selected key unchanged.

Version labels describe existing assets; they never request a crop. A portrait work can have portrait 1080p and 4K versions, and Original Ratio keeps its uploaded ratio. The automatic 1080p version is resize-only and never crops, rotates, stretches, pads, changes ratio or upscales.

Cursor pagination

Treat every cursor as an opaque string. Send the returned cursor unchanged and stop when no next cursor is provided.

{
  "data": [/* resources */],
  "page": {
    "limit": 20,
    "total": 137,
    "has_more": true,
    "next_cursor": "eyJvZmZzZXQiOjIwfQ"
  },
  "links": {
    "self": "/v1/artworks?limit=20",
    "next": "/v1/artworks?limit=20&cursor=eyJv..."
  }
}

• Maximum page size is 100.Requested limits are clamped to the supported range.
• Defaults vary by endpoint.Search GET defaults to 24; relationship lists may default to 50.
• Invalid cursors return 400.Do not decode, edit or concatenate cursor content.

Field projection

Use fields to reduce payload size. GET endpoints accept comma-separated dot paths; POST endpoints accept a string array. Stable fields such as id, type, version and updated_at remain available.

curl --get "https://collection.vieunite.com/v1/artworks" \
  -H "Authorization: Bearer $VIEUNITE_TENANT_TOKEN" \
  -H "Accept: application/json" \
  --data-urlencode "fields=id,type,name,artist,assets.thumbnail,version,updated_at"

Sensitive and restricted content

Standard list operations exclude content that is not available for the tenant and context. Using include_sensitive=true requires safety:sensitive:read. Restricted asset delivery can additionally require rights:restricted:read.