Lifecycle

Understanding the six stages of a server's life in VClarity helps you predict the traffic your API will see, and when. Each stage links to the reference page that specifies it.

1. Add server

The user types your URL (and optionally a user token) into the app. The gateway normalizes it to an origin, looks the origin up in the publisher registry, and reads your registered manifest — your server is not contacted at all during discovery. The gateway then negotiates the protocol version and runs the auth flow your manifest's auth.type asks for. The device stores the origin and any tokens in its secure store.

If the origin isn't registered, the user sees "this site is not a registered VCP publisher" and nothing else happens — the registry is the single gate deciding which origins the gateway will ever contact.

2. Import

The app pages through GET /collections, then GET /collections/{id}/items for the collections the user selects. If you advertise the changes capability, it also stores your initialdelta-sync cursor now. Expect a burst of paginated list requests here — this is the heaviest read load your integration will see per user.

3. Playback

At play time the app fetches GET /videos/{id}, picks a source, and streams media directly from your CDN — the gateway is not in the media path. Expiring or CDN-rejected source URLs are refreshed once per playback attempt via GET /videos/{id}/sources, per theexpiry contract.

4. Interact

Reactions, playlist edits, and any other capability writes go through the gateway following the write model: idempotent verbs, optimistic concurrency, and an offline queue that replays in order when the device reconnects.

5. Re-sync

Periodically the app reconciles its local library with your catalog. With thechanges capability it asks foreverything since its stored cursor; without it, it re-lists and compares updated_at timestamps — which is why updated_atmust change whenever an object or its items change.

6. Remove server

The device deletes its stored tokens and should trigger your revocation endpoint's equivalent — though users deleting the device from your site's settings page achieves the same thing. Nothing on your side needs to poll for liveness: an abandoned grant simply expires or gets revoked.