---
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`

## Request

- Base URL: `https://api.smokeball.com`
- URL: `https://api.smokeball.com/matters/{matterId}/documents/files/{fileId}/preview`
- Auth: API key in header `x-api-key` and API key in header `Authorization`

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 to the specified matter, 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

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

---

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