---
title: "Request a video export"
method: POST
path: "/v1/downloads"
tags: ["downloads"]
---

# Request a video export

`POST /v1/downloads`

## Request

- Base URL: `https://developer.coram.ai`
- URL: `https://developer.coram.ai/v1/downloads`
- Auth: API key in header `X-Auth-Token`

Asks the NVRs to export one clip per entry in `clips`. The export runs in
the background; poll the download by its id for status and links, or
subscribe to the `download_finished` webhook.
Requires the write:* scope and the REGULAR role, and the creator must have
access to every camera. Organizations that enforce face blur on exports
get 403, because developer API downloads cannot be blurred.

Each clip can be at most 2 hours long. The request body can be at most
1 MiB; a larger body returns 400. Within that size there is no limit on
the number of clips: each NVR queues its exports and works through
them, so a request with many clips takes longer to finish.

Send an `Idempotency-Key` header to retry safely. A retry with the same
key and body returns the original download with the
`Idempotent-Replayed: true` header; the same key with a different body
returns 422. Because a replay returns the original download, a download
that ended `failed` is not retried by sending its key again. Send the
request again with a new `Idempotency-Key` to start a new export.

## Headers

- `Idempotency-Key` string

## Request body

- CreateDownloadRequest
  - `clips` DownloadClip[], required
    - `mac_address` string, required
    - `start_time` string, date-time, required
    - `end_time` string, date-time, required: After start_time, at most 2 hours later, and no more than 1 minute in the future.
  - `name` string, nullable: 1 to 200 characters after trimming whitespace.
  - `include_timestamp_overlay` boolean
  - `include_audio` boolean: Ignored when the organization mutes audio on all exports.
  - `motion_only` boolean

## Response `202`

The download was accepted, or replayed for a repeated Idempotency-Key

- CreateDownloadResponse
  - `download_id` integer, required
  - `status` 'processing' | 'ready' | 'failed' | 'cancelled' | 'expired', required

## Other responses

- `400`: The body or Idempotency-Key header is invalid, the body is larger than 1 MiB, or a camera is missing or not accessible to the API key's creator
- `401`: Missing or invalid API key
- `403`: API key lacks the required scope or role, or the organization enforces face blur on exports
- `404`: Developer API downloads are not enabled for this organization
- `422`: The Idempotency-Key was already used with a different request

## Changes

- **2026-11-02** `00df3cfc762f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/coram/apis/coram-api/changes/v1/downloads/post.md)

---

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