---
title: "Get or create a preview"
method: POST
path: "/matters/{matterId}/documents/files/{fileId}/preview"
tags: ["Files"]
---

# Get or create a preview

`POST /matters/{matterId}/documents/files/{fileId}/preview`

Returns a PDF preview of the current version of the specified file, creating it if it does not exist yet.
            
The 202 response has two shapes:
- Preview already exists: 'downloadUrl' contains a presigned URL to the PDF preview and 'expiry' is its expiry time.
  The URL is valid for 1 day.
- Preview does not exist yet: a conversion is requested and processed asynchronously; 'downloadUrl' and 'expiry' are null.
  Poll the 'Location' header (GetPreviewById) until it returns 200.
            
The preview is always generated as a PDF, regardless of the source file type.
Previews are keyed by document version, so uploading a new version of the file produces a new preview.

## Path parameters

- `matterId` string, required
- `fileId` string, required

## Response `202`

When the request is accepted. Returns a 'PreviewFileInfo' object, with 'downloadUrl' and 'expiry' populated if the preview already exists and null if conversion is still pending.

- PreviewFileInfo
  - `fileId` string, nullable — Unique identifier of the requested file
  - `documentVersionId` string, nullable — Unique identifier of the document version the preview was generated from. Pass this to GetPreviewById.
  - `downloadUrl` string, nullable — Temporary presigned URL to download the PDF preview. Valid for 1 day. Null when the preview has not been generated yet (conversion is pending); poll GetPreviewById until it is available.
  - `expiry` string, date-time, nullable — Expiry date/time (UTC) after which the download link is no longer accessible. Null when the preview has not been generated yet (conversion is pending).

## Other responses

- `400` — When a supplied id is not a valid GUID.
- `403` — When the file does not belong to the authenticated account or does not exist.
- `404` — When the file exists but has no uploaded version yet.

## Changes

- **2026-08-26** `db1b8a86b58e` — 1 info
  - added the optional property `errors` to the response with the `400` status

[Change history](https://skmtc.dev/smokeball/apis/api/changes/matters/:matterId/documents/files/:fileId/preview/post.md)

---

[API](https://skmtc.dev/smokeball/apis/api.md) · [All operations](https://skmtc.dev/smokeball/apis/api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/smokeball/api/revisions/db1b8a86b58e/schema)