List library videos

GET

/videos

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

• Braiv Public API

Lists accessible videos newest first. Pass the previous response’s token to continue. Required scope: videos:read.

Authorizations

• bearerAuth
• apiKeyHeader

Parameters

Query Parameters

limit

integer

default: 20 >= 1 <= 100

Maximum videos to return. Values above 100 are capped at 100.

pageToken

string

>= 1 characters

Last video ID from the previous page. An unknown token is ignored.

Responses

200

A page of videos.

Media type application/json

object

videos

required

Videos in descending creation order.

Array<object>

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})?$/

nextPageToken

required

Last video ID to pass to the next request, or null at the end.

string | null

Example

{
  "videos": [
    {
      "id": "vid_01JZ8M6A",
      "status": "ready",
      "title": "Launch demo",
      "duration": 184.2,
      "defaultLanguageCode": "en"
    }
  ],
  "nextPageToken": "vid_01JZ7ZZZ"
}

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

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

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