---
title: "Get short-lived playback and download links for one of your videos"
method: GET
path: "/v1/files/{uuid}/video-link"
tags: ["Files"]
---

# Get short-lived playback and download links for one of your videos

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

## Request

- Base URL: `https://contentmaschine.ai/api`
- URL: `https://contentmaschine.ai/api/v1/files/{uuid}/video-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`)

Built for video players such as the MCP `show_video` tool. This call is free: no credits
are charged, no model is called and no bytes are returned. The links expire after 15
minutes.

- `video_url` plays the video inline with its real content type; `download_url` saves it.
- `poster_url` is the stored thumbnail when there is one, otherwise `null`.
- **Every URL is a credential for 15 minutes**: anyone holding it can read the file. Do
  not log it or pass it on.
- A video stored only on the server disk, or one that cannot be presigned right now,
  answers 200 with `available: false`, every URL `null` and `reason` saying why.

Only MP4, WebM and QuickTime videos are served. A file that is unknown, not yours, not
one of those video types, or readable only by a container scope your token lacks is a
404, the same 404 for all of them. 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.

## Path parameters

- `uuid` string, uuid, required

## Response `200`

Playback, download and poster links valid for 15 minutes.

- object
  - `success` boolean
  - `data` object
    - `uuid` string, uuid
    - `file_name` string
    - `mime_type` 'video/mp4' | 'video/webm' | 'video/quicktime'
    - `width` integer, nullable
    - `height` integer, nullable
    - `poster_url` string, nullable: Presigned inline URL for the stored thumbnail. A credential.
    - `video_url` string, nullable: Presigned inline URL that plays the video. A credential.
    - `download_url` string, nullable: Presigned download URL for the original. A credential.
    - `expires_at` string, date-time, nullable
    - `expires_in_seconds` integer, nullable
    - `available` boolean
    - `reason` 'local_only' | 'link_unavailable' | 'null', nullable
  - `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, not a playable video, 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)