Skip to content
Braiv Docs

Prepare a download

POST
/videos/{videoId}/downloads
 
curl --request POST \
  --url https://api.braiv.co/v1/videos/vid_01JZ8M6A/downloads \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: import-launch-demo-20260901' \
  --data '{ "artifact": "language_video", "language": "es" }'

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

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
videoId
required
string
>= 1 characters

Braiv library video document ID.

Example 
vid_01JZ8M6A

Header Parameters

Section titled “Header Parameters ”
Idempotency-Key
string
>= 1 characters

Caller-generated key for safe POST retries. The API retains the first JSON response for 24 hours. Reusing a key with another path or body returns 409 IDEMPOTENCY_REPLAY.

Example 
import-launch-demo-20260901

Request Body required

Section titled “Request Body required ”
Media type application/json
object
artifact
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.

string
Allowed values: language_video source bundle
language

Language video target; otherwise optional.

string
>= 2 characters <= 16 characters /^[A-Za-z]{2,3}(?:-[A-Za-z]{2,4})?$/
Example 
{
  "artifact": "language_video",
  "language": "es"
}

Responses

Section titled “ Responses ”

202

Section titled “202 ”

Download preparation queued.

Media type application/json
object
downloadRequestId
required

Created download request ID.

string
jobId
required

Pollable download job ID.

string
artifact
required

Requested download package.

string
Allowed values: language_video source bundle
language
required
One of:

ISO-style language or locale code accepted by the underlying product.

string
>= 2 characters <= 16 characters /^[A-Za-z]{2,3}(?:-[A-Za-z]{2,4})?$/
tier
required

Download entitlement selected for this request.

string
Allowed values: full sample
status
required

Initial download preparation state.

string
Allowed values: queued processing ready failed
Example 
{
  "downloadRequestId": "dl_01",
  "jobId": "download_dl_01",
  "artifact": "language_video",
  "language": "es",
  "tier": "full",
  "status": "queued"
}

400

Section titled “400 ”

Request fields are missing, malformed, out of bounds, or mutually inconsistent.

Media type application/json
object
error
required

Structured public API error envelope.

object
code
required

Stable machine-readable error code.

string
Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL
message
required

Human-readable error summary.

string
details
required

Machine-readable operation-specific context; empty when unavailable.

object
key
additional properties
any
Example 
{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "The request contains invalid or missing fields.",
    "details": {}
  }
}

401

Section titled “401 ”

A supported authentication header is missing or contains an invalid Public API key.

Media type application/json
object
error
required

Structured public API error envelope.

object
code
required

Stable machine-readable error code.

string
Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL
message
required

Human-readable error summary.

string
details
required

Machine-readable operation-specific context; empty when unavailable.

object
key
additional properties
any
Examples

Authentication header missing

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Missing API key.",
    "details": {}
  }
}

403

Section titled “403 ”

Authentication succeeded, but the required scope, workspace role, or resource permission is missing.

Media type application/json
object
error
required

Structured public API error envelope.

object
code
required

Stable machine-readable error code.

string
Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL
message
required

Human-readable error summary.

string
details
required

Machine-readable operation-specific context; empty when unavailable.

object
key
additional properties
any
Examples
Example scope 
{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "The API key lacks the required scope.",
    "details": {}
  }
}

404

Section titled “404 ”

The resource does not exist or is not accessible to the caller.

Media type application/json
object
error
required

Structured public API error envelope.

object
code
required

Stable machine-readable error code.

string
Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL
message
required

Human-readable error summary.

string
details
required

Machine-readable operation-specific context; empty when unavailable.

object
key
additional properties
any
Example 
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found.",
    "details": {}
  }
}

409

Section titled “409 ”

The Idempotency-Key was reused with a different path or request body.

Media type application/json
object
error
required

Structured public API error envelope.

object
code
required

Stable machine-readable error code.

string
Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL
message
required

Human-readable error summary.

string
details
required

Machine-readable operation-specific context; empty when unavailable.

object
key
additional properties
any
Example 
{
  "error": {
    "code": "IDEMPOTENCY_REPLAY",
    "message": "Idempotency-Key was reused with a different request.",
    "details": {
      "pathMatch": true,
      "hashMatch": false
    }
  }
}

422

Section titled “422 ”

Downloads are unavailable, or the selected dub is only a preview.

Media type application/json
object
error
required

Structured public API error envelope.

object
code
required

Stable machine-readable error code.

string
Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL
message
required

Human-readable error summary.

string
details
required

Machine-readable operation-specific context; empty when unavailable.

object
key
additional properties
any
Example 
{
  "error": {
    "code": "UNAUTHENTICATED"
  }
}

429

Section titled “429 ”

The API key exceeded its allowed concurrency or request rate. Retry after in-flight work completes or the limit resets.

Media type application/json
object
error
required

Structured public API error envelope.

object
code
required

Stable machine-readable error code.

string
Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL
message
required

Human-readable error summary.

string
details
required

Machine-readable operation-specific context; empty when unavailable.

object
key
additional properties
any
Example 
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "API key concurrency limit reached",
    "details": {}
  }
}

500

Section titled “500 ”

An unexpected server error occurred.

Media type application/json
object
error
required

Structured public API error envelope.

object
code
required

Stable machine-readable error code.

string
Allowed values: UNAUTHENTICATED INVALID_API_KEY INSUFFICIENT_SCOPE PERMISSION_DENIED ROLE_CANNOT_PRODUCE NOT_FOUND INVALID_ARGUMENT UNSUPPORTED_SOURCE DURATION_UNKNOWN INSUFFICIENT_CREDITS CONFLICT ALREADY_EXISTS IDEMPOTENCY_REPLAY RATE_LIMITED PREVIEW_NOT_DOWNLOADABLE DOWNLOAD_TIER_NONE FAILED_PRECONDITION GONE METHOD_NOT_ALLOWED INTERNAL
message
required

Human-readable error summary.

string
details
required

Machine-readable operation-specific context; empty when unavailable.

object
key
additional properties
any
Example 
{
  "error": {
    "code": "INTERNAL",
    "message": "An unexpected error occurred.",
    "details": {}
  }
}