---
title: "Replace site route previews"
method: PUT
path: "/sites/{site_id}/route-previews"
tags: ["Sites"]
---

# Replace site route previews

`PUT /sites/{site_id}/route-previews`

## Request

- Base URL: `https://api.cloudglue.dev/v1`
- URL: `https://api.cloudglue.dev/v1/sites/{site_id}/route-previews`
- Auth: HTTP bearer

Replace the site's complete set of per-route unfurl previews. Each entry maps a route within the site (e.g. a clip page) to its own preview card and hero share, so links to that page unfurl distinctly in Slack instead of with the site-wide hero. An optional startSeconds/endSeconds window makes the unfurled player serve only that segment of the hero (trimmed at the asset’s HLS segment boundaries — see the field descriptions). The set is replaced wholesale — typically written by the same pipeline that publishes the site — and an empty array clears all route previews. Routes are stored in canonical form: hash-router prefixes ('#/'), query strings, and surrounding slashes are stripped, so '/clip/intro', 'clip/intro/', and '#/clip/intro' all name the same route. Links to routes with no registered preview fall back to the site-level preview fields.

## Path parameters

- `site_id` string, uuid, required

## Request body

- ReplaceSiteRoutePreviewsRequest
  - `previews` SiteRoutePreviewInput[], required: The site's complete set of route previews. Replaces whatever was stored before — routes omitted here lose their preview (and fall back to the site-level hero). An empty array clears all route previews.
    - `route` string, required: The site route this preview applies to. Stored and matched in canonical form: hash-router prefixes ('#/'), query strings, and surrounding slashes are stripped, so '/clip/intro', 'clip/intro/', and '#/clip/intro' all name the same route. Must not be empty after canonicalization — the site root unfurls with the site-level preview fields.
    - `previewTitle` string: Preview card title. Falls back to the hero share's own title (then its filename) when unset.
    - `previewDescription` string: Preview card description. Falls back to the hero share's own description when unset. Slack truncates at 200 characters.
    - `previewImageUrl` string, uri: Preview card image. Must be a publicly fetchable URL (e.g. a share's preview_url) — site asset URLs sit behind the private-site gate and won't render. Falls back to the hero share's thumbnail when unset.
    - `previewShareId` string, uuid, required: The route's hero share: what a link to this page plays when unfurled by the Cloudglue Slack app. Must be a video share owned by the same account; on a public site it must be a public share.
    - `startSeconds` number: Clip window start, in seconds (fractional allowed). Requires endSeconds; the unfurled player then plays only the [startSeconds, endSeconds] window of the hero share. Precision note: the stream is trimmed with Mux instant clipping, which cuts at the asset's HLS segment boundaries (start rounds down, end rounds up) — not frame-accurate, so the served clip can include a few extra seconds on either side depending on the asset's segment length.
    - `endSeconds` number: Clip window end, in seconds (fractional allowed). Requires startSeconds and must be greater than it. Served at HLS segment granularity — see startSeconds.

## Response `200`

The stored route previews (routes in canonical form)

- SiteRoutePreviewList
  - `previews` SiteRoutePreview[], required
    - `id` string, uuid, required
    - `route` string, required: The site route this preview applies to. Stored and matched in canonical form: hash-router prefixes ('#/'), query strings, and surrounding slashes are stripped, so '/clip/intro', 'clip/intro/', and '#/clip/intro' all name the same route. Must not be empty after canonicalization — the site root unfurls with the site-level preview fields.
    - `previewTitle` string, nullable: Preview card title. Falls back to the hero share's own title (then its filename) when unset.
    - `previewDescription` string, nullable: Preview card description. Falls back to the hero share's own description when unset. Slack truncates at 200 characters.
    - `previewImageUrl` string, uri, nullable: Preview card image. Must be a publicly fetchable URL (e.g. a share's preview_url) — site asset URLs sit behind the private-site gate and won't render. Falls back to the hero share's thumbnail when unset.
    - `previewShareId` string, uuid, required: The route's hero share: what a link to this page plays when unfurled by the Cloudglue Slack app. Must be a video share owned by the same account; on a public site it must be a public share.
    - `startSeconds` number, nullable: Clip window start, in seconds (fractional allowed). Requires endSeconds; the unfurled player then plays only the [startSeconds, endSeconds] window of the hero share. Precision note: the stream is trimmed with Mux instant clipping, which cuts at the asset's HLS segment boundaries (start rounds down, end rounds up) — not frame-accurate, so the served clip can include a few extra seconds on either side depending on the asset's segment length.
    - `endSeconds` number, nullable: Clip window end, in seconds (fractional allowed). Requires startSeconds and must be greater than it. Served at HLS segment granularity — see startSeconds.
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required

## Other responses

- `400`: Invalid route previews (empty or duplicate canonical routes, non-video heroes, private heroes on a public site, or an invalid clip window)
- `404`: Site not found, or a previewShareId does not reference a share in this account

## Changes

- **2026-10-30** `23d3f240819f`: 2 info
  - added the optional property `code` to the response with the `400` status
  - added the optional property `code` to the response with the `404` status
- **2026-08-25** `b2cb59ebd45f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cloudglue/apis/cloudglue-api/changes/sites/:site_id/route-previews/put.md)

---

[API](https://skmtc.dev/cloudglue/apis/cloudglue-api.md) - [All operations](https://skmtc.dev/cloudglue/apis/cloudglue-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cloudglue/apis/cloudglue-api/revisions/23d3f240819f?raw)