Casting

Casting lets a user show one of their documents on a second screen (for example a TV via Chromecast). The flow is:

1. The user creates a cast session for a document. This returns a random token and a cast_url.
2. The cast_url is opened on the receiving device (a Cast receiver or a browser).
3. The receiver polls two token-authenticated endpoints to check whether the session is still valid and to fetch the document to render.

A session stays alive as long as the receiver keeps polling; it expires after a period of inactivity (currently 24 hours). The owner can list and revoke active sessions at any time.

The three …/cast/sessions… endpoints require the request to be authenticated as the document’s owner. The …/cast/:token/… endpoints require no authentication — the token in the URL is the credential — and are CORS-enabled so a receiver on another origin can call them.

Creating a cast session

Route

POST /api/v1/cast/sessions

Request payload

{
  "document_id": "T0g2oxgTQFaaONWDe4Spvw",
  "device_name": "Living Room TV"
}

Return value

Name	Type	Description
id	string	Unique identifier of the cast session.
token	string	Secret token identifying the session. Part of the cast_url.
cast_url	string	URL to open on the receiving device, of the form …/cast/token“.
expires_at	string	Timestamp (RFC 3339) of when the session expires.

Listing active sessions of a document

Returns all active (non-revoked, non-expired) cast sessions for one of the current user’s documents.

Route

GET /api/v1/cast/sessions/documentId

Return value

A JSON array of session objects:

Name	Type	Description
id	string	Unique identifier of the cast session.
document_id	string	ID of the document being cast.
device_name	string	Name of the receiving device.
created_at	string	Timestamp (RFC 3339) of when the session was created.
last_activity_at	string	Timestamp (RFC 3339) of the last receiver activity.
expires_at	string	Timestamp (RFC 3339) of when the session expires.
cast_url	string	URL of the receiving device.

Revoking a session

Revokes one of the current user’s cast sessions.

Route

DELETE /api/v1/cast/sessions/sessionId

Return value

No content (HTTP status code 204) upon success.

Checking a session (receiver)

Used by the receiving device to poll whether the session is still valid and whether the document has changed. Requires no authentication other than the token.

Route

GET /api/v1/cast/token/check

Return value

Name	Type	Description
valid	boolean	Whether the session is still valid.
document_id	string	Optional: ID of the document being cast (only when valid).
last_modified	string	Optional: Timestamp (RFC 3339) of the document’s last change; use it to detect updates.

An invalid, expired, or revoked session returns { "valid": false } with HTTP status code 200.

Fetching the document (receiver)

Returns the full document payload and its plugin bundle for the receiver to render. Requires no authentication other than the token.

Route

GET /api/v1/cast/token/document

Return value

{
  "document": {
    "id": "…",
    "title": "…",
    "updated": "2026-01-01T12:00:00Z",
    "data": [ … ],
    "settings": { … },
    "style": { … },
    "customTheme": { … }
  },
  "plugin": { … }
}

An invalid or expired session returns HTTP status code 401.

The receiver page

The cast_url returned when creating a session points at a Vizzlo-hosted receiver page (https://vizzlo.com/cast/token“) that renders the document and polls the endpoints above. There is also a Cast SDK receiver at https://vizzlo.com/cast/receiver for use inside a Chromecast receiver application. Neither page requires the user to be logged in.