---
title: "Get a short-lived download link and a preview for a file you own"
method: GET
path: "/v1/files/{uuid}/download-link"
tags: ["Files"]
---

# Get a short-lived download link and a preview for a file you own

`GET /v1/files/{uuid}/download-link`

## Request

- Base URL: `https://contentmaschine.ai/api`
- URL: `https://contentmaschine.ai/api/v1/files/{uuid}/download-link`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://contentmaschine.ai/api/oauth/authorize`, token URL `https://contentmaschine.ai/api/oauth/token`)

The JSON form of `GET /v1/files/{uuid}/download`, built for agent callers that cannot
follow an authenticated URL or show a binary body. No credits are charged and the file
stays private: its visibility is not changed.

- `download_url` is a presigned, unauthenticated URL for the ORIGINAL file, valid for 15
  minutes (`expires_at`). **It is a credential for that time**: anyone holding it can
  read the file. Do not log it or pass it on. It is `null` for a file stored only on the
  server disk (no expiring link can be issued); `link_unavailable_reason` then says why.
- `preview` is set for raster images only: a reduced JPEG (at most 1024 px on the long
  edge and about 350 KB), base64-encoded. It is never the original bytes. `null` for
  other files, SVG, or an image that cannot be decoded.

Authorization is the same two-layer check as the download route: `files:read` at the
gate, then the read scope of the file's own container. A denial is a 404, never a 403.

## Path parameters

- `uuid` string, uuid, required

## Response `200`

File metadata, a 15-minute download link and, for images, a preview.

- object
  - `success` boolean
  - `data` object
    - `uuid` string, uuid
    - `file_name` string
    - `mime_type` string
    - `size_bytes` integer
    - `download_url` string, nullable: Presigned URL for the original file, valid 15 minutes. A credential.
    - `view_url` string, nullable: Presigned URL that opens the original in the browser instead of downloading it, valid 15 minutes. Raster images only. A credential.
    - `expires_at` string, date-time, nullable
    - `expires_in_seconds` integer, nullable
    - `link_unavailable_reason` string, nullable
    - `preview` object, nullable
      - `mime_type` 'image/jpeg'
      - `base64` string: Reduced JPEG, base64. Never the original bytes.
      - `width` integer
      - `height` integer
  - `timestamp` string, date-time

## Other responses

- `401`: Missing or invalid API key.
- `403`: The token does not hold files:read.
- `404`: Unknown file, not yours, OR readable only by a container scope your token lacks.
- `default`: Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.

---

[API](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api.md) · [All operations](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api/revisions/28c74f46051c?raw)