Get a prepared download

GET

/downloads/{downloadRequestId}

curl --request GET \
  --url https://api.braiv.co/v1/downloads/example \
  --header 'Authorization: Bearer <token>'

• Braiv Public API

Returns a URL when ready. Failed download preparation is a terminal 200 response with status: failed and an error object. Required scope: downloads:write.

Authorizations

• bearerAuth
• apiKeyHeader

Parameters

Path Parameters

downloadRequestId

required

string

>= 1 characters

Download request document ID returned by createDownload.

Responses

200

Download is ready or terminally failed.

Media type application/json

object

id

required

Download request ID.

string

status

required

Normalized to ready or failed at terminal state; otherwise stored queue status.

string

tier

Download entitlement applied.

string

Allowed values: full sample

truncated

required

True for sample-tier artifacts.

boolean

maxDurationSeconds

required

Sample duration cap or null for full downloads.

number | null

url

required

Prepared artifact URL when ready.

string | null format: uri

error

required

One of:

object

object

key

additional properties

any

null

null

jobId

required

Pollable download job ID.

string

Examples

{
  "id": "dl_01",
  "status": "ready",
  "tier": "full",
  "truncated": false,
  "maxDurationSeconds": null,
  "url": "https://storage.googleapis.com/...zip",
  "error": null,
  "jobId": "download_dl_01"
}

{
  "id": "dl_01",
  "status": "failed",
  "tier": "full",
  "truncated": false,
  "maxDurationSeconds": null,
  "url": null,
  "error": {
    "message": "Render failed"
  },
  "jobId": "download_dl_01"
}

202

Download is still queued or processing.

Media type application/json

object

id

required

Download request ID.

string

status

required

Normalized to ready or failed at terminal state; otherwise stored queue status.

string

tier

Download entitlement applied.

string

Allowed values: full sample

truncated

required

True for sample-tier artifacts.

boolean

maxDurationSeconds

required

Sample duration cap or null for full downloads.

number | null

url

required

Prepared artifact URL when ready.

string | null format: uri

error

required

One of:

object

object

key

additional properties

any

null

null

jobId

required

Pollable download job ID.

string

Example

{
  "id": "dl_01",
  "status": "processing",
  "tier": "full",
  "truncated": false,
  "maxDurationSeconds": null,
  "url": null,
  "error": null,
  "jobId": "download_dl_01"
}

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": {}
  }
}

API key invalid

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key",
    "details": {}
  }
}

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

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": {}
  }
}

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

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": {}
  }
}