Skip to main content
Use the preview endpoints when your app, report, or link card needs a picture of a model: a thumbnail in a project list, an image in a generated report, or an Open Graph image when a link is shared. Speckle renders previews in the background after each publish and serves them as images. For an interactive 3D view, embed the viewer instead.

Get a preview

Request the preview of a project’s latest version:
You should get a PNG. Public projects need no token; for a private project, add -H "Authorization: Bearer YOUR_TOKEN" with a token that has the streams:read scope. The paths keep the server’s original words: branches for models and commits for versions. URL-encode the / in a nested model name.

Other images of the same preview

Add an angle segment to the end of any path, such as /preview/{projectId}/spin, and ?postprocess=og for a 1200×627 Open Graph image with the project name over the preview. Which angles exist depends on the server: A key the preview does not have returns a placeholder with X-Preview-Error-Code: ANGLE_NOT_FOUND.

When there is no preview yet

The endpoints always answer with an image. A project, model, or version without a preview gets a placeholder PNG, and the first request for an object without a preview queues its render. While a render is queued, running, or failed, the response carries X-Preview-Error: true and an X-Preview-Error-Code, and it is not cached. Check that header rather than the status code if your app needs to know whether it got a real preview. Errors differ by server. Speckle Cloud and Speckle Enterprise Server answer with the error status (401, 403, 404) and a placeholder image. The open-source Speckle Server answers 200 with an error image, so check the image, not the status.

Self-hosted servers

Previews need the preview service running alongside the server, with Redis for its job queue. On Speckle Cloud it is already running. For a self-hosted deployment, see the server documentation.
Last modified on November 14, 2026