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

Use GET /v1/search for a search box and simple filters. This request looks for landscape artwork and collections, with counts grouped by medium and movement:

curl --get "https://collection-test.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"

An artwork matches orientation=landscape if at least one available image version is landscape. The original artwork might still be portrait. Use the matching version’s dimensions for display. Orientation facet counts count each artwork once per orientation, so one artwork can appear in more than one group.

Advanced search

Use POST /v1/search when the filters are easier to express as JSON. Here, fields selects the response data and facets asks for counts you can show beside filter options:

curl --request POST "https://collection-test.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

Render the returned data, then use page.next_cursor for the next request. Keep the same search and filters while paging; start again without a cursor when they change. Stop when page.has_more is false.

{
  "data": [{
    "id": "art_456",
    "type": "artwork",
    "name": "Example artwork",
    "version": 7,
    "updated_at": "2026-09-16T12:00:00Z"
  }],
  "page": {
    "limit": 1,
    "total": 137,
    "has_more": true,
    "next_cursor": "eyJvZmZzZXQiOjF9"
  },
  "links": {
    "self": "/v1/artworks?limit=1",
    "next": "/v1/artworks?limit=1&cursor=eyJvZmZzZXQiOjF9"
  }
}

• 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

Request only the fields your screen needs. GET endpoints accept comma-separated paths; POST endpoints accept an array of paths. The API always retains id, type, version and updated_at. Request an entire array such as available_versions; array members cannot be projected individually.

curl --get "https://collection-test.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.