Store references, not replicas.

The integration model

The Collection API separates editor selection from content delivery. A hosted experience can help the editor choose, while your backend controls credentials, persistence, rendering and publication checks.

Production and Test are isolated

Each environment has its own API, hosted Picker, SDK origin and tenant credentials. Use Test for integration work, then move all three URLs and the issued credential to Production as one deployment change.

Never send a Test token to Production or a Production token to Test. Register the exact CMS callback origins separately in each environment.

Resources

Artwork and collection are selectable. Artists and categories help organise discovery but are not themselves Picker selections.

Durable references

A reference is intentionally smaller than an artwork response. It survives metadata edits, asset rotations and rights changes, and it can be validated before publication.

{
  "provider": "vieunite-art-collection",
  "type": "artwork",
  "id": "art_456",
  "rendition": "crop"
}

{
  "provider": "vieunite-art-collection",
  "type": "collection",
  "id": "col_123"
}

Artwork versions

rendition identifies the artwork version selected by an editor. It is not a second artwork identity or a requested output shape. Treat the value as an opaque key.

• Every new artwork selection includes its rendition key.The Picker only allows approved versions with both a delivery asset and a safe thumbnail.
• Labels describe the actual asset.resolution_class, orientation, and ratio are independent metadata; they do not request a generated crop.
• Automatic 1080p has one composition-safe rule.Prefer a 4K curated crop; only when no crop exists may a 4K original be proportionally resized. A 1080p crop suppresses the original fallback. Nothing is cropped, rotated, stretched, padded, ratio-changed, or upscaled.
• Original Ratio stays Original Ratio.The original version never displays a 4K or 1080p suffix; orientation and ratio remain separate metadata.
• Square is source-backed.It appears only when a curator supplied a validated square composition. Missing square versions are not synthesized.
• Collections do not carry a rendition.A collection can contain artworks with different versions.
• Resolve with the saved rendition.This validates that the editor's chosen version is still available; request its signed delivery separately.
• Handle rendition_unavailable.Rights or asset changes can make an old version unavailable.

Preview responses expose only nested preview dimensions for safe thumbnails. Authenticated responses additionally expose nested source and delivery dimensions for every available version. ratio remains accepted for legacy read-only references and as geometric metadata, but new integrations persist rendition.

Availability, rights and safety

A record can exist while being unavailable to a specific tenant or context. Plan level, publication window, rights, audience and safety policy are evaluated when the API lists or resolves content.

Use reference validation immediately before publishing when stale or unavailable artwork would block a content release.

Preview experience versus full data

The public demos and hosted Picker use a selectively protected preview experience. Public facts such as title, artist and medium remain useful for discovery, while curated copy, additional taxonomy, URLs and original resolution stay protected.

Preview surfaces expose safe thumbnails for every available version. They never expose original resolution or storage URLs. Production CMS rendering and metadata retrieval should always use the authenticated server API.

Batch operations can partially succeed

One unavailable item does not necessarily fail an entire batch. Design CMS workflows to inspect each result.