Get a video

GET

/videos/{videoId}

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

• Braiv Public API

Returns the normalized library record and current import/transcript projections. Required scope: videos:read.

Authorizations

• bearerAuth
• apiKeyHeader

Parameters

Path Parameters

videoId

required

string

>= 1 characters

Braiv library video document ID.

Example

vid_01JZ8M6A

Responses

200

The accessible video resource.

Media type application/json

object

id

required

Library video ID.

string

status

required

Overall normalized video processing state.

string

Allowed values: queued processing ready failed

title

Current video title.

string

description

Current video description.

string

duration

Media duration in seconds.

number

posterUrl

Current poster image URL.

string format: uri

provider

Internal source provider label.

string

mediaType

Ingested media kind.

string

Allowed values: video audio

defaultLanguageCode

Detected or selected source language.

string

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

url

Primary playback URL when available.

string format: uri

urlMulti

Playback URLs keyed by language code.

object

key

additional properties

string format: uri

workspaceId

Owning workspace, if any.

string

folderIds

Studio folder ids this video belongs to (UserVideos.tags).

Array<string>

createdAt

ISO creation timestamp.

string format: date-time

import

Import pipeline projection.

object

status

required

Current lifecycle state for this video subresource.

string

Allowed values: queued processing ready failed

language

Language represented by the subresource.

string

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

transcript

Source transcription projection.

object

status

required

Current lifecycle state for this video subresource.

string

Allowed values: queued processing ready failed

language

Language represented by the subresource.

string

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

Example

{
  "id": "vid_01JZ8M6A",
  "status": "ready",
  "title": "Launch demo",
  "duration": 184.2,
  "mediaType": "video",
  "defaultLanguageCode": "en",
  "import": {
    "status": "ready"
  },
  "transcript": {
    "status": "ready",
    "language": "en"
  }
}

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