RelayrtcDocs
Get started
Documentation
REST API v1

Assets REST API

Read recording assets and issue scoped playback or MP4 download grants.

On this page
MethodRouteResult
GET/v1/assets/{assetId}200 MediaAsset
POST/v1/assets/{assetId}/access-grants201 AssetAccessGrant
POST/v1/assets/{assetId}/access-grants/revoke200 { assetId, revoked: true }
DELETE/v1/assets/{assetId}202 associated RecordingResource

Metadata and grant issuance require recordings:read and a matching secret-key scope or console membership. Deletion and link revocation require recordings:create or owner/admin membership. Mutations require Idempotency-Key. Scope and Origin behavior match the recordings API.

Metadata contains id, recordingId, streamId, broadcastId, state, partial, durationSeconds, region, formats, hasThumbnail, codecs, sizeBytes and expiresAt. Formats remain empty until ready. HLS is present on ready assets; MP4 requires a completed requested export. Audio-only assets have no thumbnail.

Grant input

FieldValues and default
actionplayback (default) or download
audienceviewer (default) or preview
ttlSecondsInteger 30–3600 seconds, default 300; capped by asset retention

Viewer grants for clip assets require publication. Operator preview can access a ready unpublished clip and additionally requires recordings:create. The result contains assetId, action, url and expiresAt. Downloads are MP4 only. Your backend must authorize the requesting viewer before issuing a grant; a browser must never receive the secret API key. Renew using a new Idempotency-Key.

The returned playback URL identifies the protected VOD manifest. Its fragment and initialization references carry the same grant. A playback grant can also authorize /assets/{assetId}/thumbnail.jpg?token=... when hasThumbnail is true. Download grants authorize only the MP4 route. Every object checks the owning resources, asset state, grant epoch, expiry and revocation. Bucket keys remain private. MP4 supports a single byte range; authorization is rechecked between chunks. All responses use private, no-store caching and configured streaming CORS origins.

Deleting an asset deletes its recording and media variants, revokes grants immediately and completes asynchronously after worker shutdown. Metadata and cumulative usage remain. Assets from failed or unfinished recordings cannot receive grants. Retention expiry makes media unavailable even if background removal has not finished.

Send an empty JSON object to POST /v1/assets/{assetId}/access-grants/revoke with an Idempotency-Key. This retires all existing playback and download grants for that asset without deleting it. The old master playlist, child playlists, initialization files, segments and MP4 range requests stop working. Authorized applications can issue new grants afterward. Console exposes Revoke existing links in recording and clip details.

Shell
curl -X POST "$RELAYRTC_API_URL/assets/$ASSET_ID/access-grants/revoke" \
  -H "Authorization: Bearer $RELAYRTC_SECRET_KEY" \
  -H "Idempotency-Key: 79d6a601-fdb0-4ed1-97cd-51a63b14d8e0" \
  -H "Content-Type: application/json" \
  -d '{}'

Playback exposes only the committed export generation. A clip grant cannot fetch its temporary, untrimmed source segments or a previous rendering attempt.