---
title: "Download a file you own"
method: GET
path: "/v1/files/{uuid}/download"
tags: ["Files"]
---

# Download a file you own

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

## Request

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

Returns the bytes, NOT a JSON envelope. Files in object storage answer 302 with a
presigned URL valid for one hour; locally stored files are streamed directly.

**The redirect target is a credential.** Anyone holding that presigned URL can read
the object until it expires. Do not log it, cache it in a shared cache, or pass it on.

**Authorization here is two-layer, and `files:read` is only the outer one.** The
route gate checks `files:read`; the handler then checks that your token can read the
file's own container. A token holding `files:read` but not `images:read` gets 404 for
an image - a 404 rather than a 403, so a denial cannot be told apart from a
nonexistent file.

Contrast `GET /api/files/download/{uuid}`, which is also documented here: it is
owner-checked but has NO scope check at all.

## Path parameters

- `uuid` string, uuid, required

## Response `200`

The file bytes (locally stored files).

## Other responses

- `302`: Redirect to a presigned URL valid for one hour. The Location header is a credential.
- `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)