---
title: "Prepare a download"
method: POST
path: "/videos/{videoId}/downloads"
tags: ["Downloads"]
---

# Prepare a download

`POST /videos/{videoId}/downloads`

## Request

- Base URL: `https://api.braiv.co/v1`
- URL: `https://api.braiv.co/v1/videos/{videoId}/downloads`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Api-Key`

Queues preparation of a language video, source asset, or bundle. Account policy determines full, sample, or unavailable download tier. Required scope: `downloads:write`.

## Path parameters

- `videoId` string, required

## Headers

- `Idempotency-Key` string

## Request body

- CreateDownloadRequest
  - `artifact` 'language_video' | 'source' | 'bundle', required: Download to prepare: `language_video` renders a video in the requested `language`; `source` returns the original source media; and `bundle` packages the video's available deliverables together.
  - `language` string: ISO-style language or locale code accepted by the underlying product.

## Response `202`

Download preparation queued.

- CreateDownloadResponse
  - `downloadRequestId` string, required: Created download request ID.
  - `jobId` string, required: Pollable download job ID.
  - `artifact` 'language_video' | 'source' | 'bundle', required: Requested download package.
  - `language` string, required: ISO-style language or locale code accepted by the underlying product.
  - `tier` 'full' | 'sample', required: Download entitlement selected for this request.
  - `status` 'queued' | 'processing' | 'ready' | 'failed', required: Normalized lifecycle shared by jobs and video projections: `queued` is waiting to start, `processing` is running, `ready` completed successfully, and `failed` reached a terminal error.

## Other responses

- `400`: Request fields are missing, malformed, out of bounds, or mutually inconsistent.
- `401`: A supported authentication header is missing or contains an invalid Public API key.
- `403`: Authentication succeeded, but the required scope, workspace role, or resource permission is missing.
- `404`: The resource does not exist or is not accessible to the caller.
- `409`: The Idempotency-Key was reused with a different path or request body.
- `422`: Downloads are unavailable, or the selected dub is only a preview.
- `429`: The API key exceeded its allowed concurrency or request rate. Retry after in-flight work completes or the limit resets.
- `500`: An unexpected server error occurred.

---

[API](https://skmtc.dev/braiv/apis/braiv-public-api.md) - [All operations](https://skmtc.dev/braiv/apis/braiv-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/braiv/apis/braiv-public-api/revisions/8ed0fd0d0a6f?raw)