RelayrtcDocs
Get started
Documentation
REST API v1

Clips

Scoped retained intervals, rolling buffer policies and clip assets.

Authenticate with a scoped secret key or console session. Reads require recordings:read; clip creation, deletion and buffer changes require recordings:create. Publishing also requires streams:publish. Project/environment scope is derived from the credential or explicit console query and checked against the stream. Ordinary viewer access uses an application-authorized asset grant, never a management key.

MethodRouteResult
GET/v1/streams/:streamId/clip-window200 data: retained recording/buffer intervals
GET / PUT/v1/streams/:streamId/buffer-policy200 policy, version
POST/v1/streams/:streamId/clips202 ClipResource
GET/v1/streams/:streamId/clips200 data, nextCursor
GET/v1/clips200 data, nextCursor for the selected project/environment
GET/v1/clips/:clipId200 ClipResource
POST/v1/clips/:clipId/publish200 ClipResource
DELETE/v1/clips/:clipId202 ClipResource

Creation body: recordingId, interval, optional cutMode (keyframe or precise), retentionSeconds and label. interval is last/seconds, media/startSeconds/endSeconds, or wall/start/end (ISO UTC). The named recording fixes the run; recursive clips are unsupported. State is queued → rendering → ready/failed → deleting → deleted. The clip resource itself is the durable asynchronous job/status handle; no separate operation resource is allocated. Publication is a synchronous availability change after ready.

ClipResource returns id, streamId, broadcastId, sourceRecordingId, recordingId (the clip's backing recording), assetId, label, state, cutMode, requestedStartSeconds, requestedEndSeconds, resolvedStartSeconds, resolvedEndSeconds, durationSeconds, published, lastError, storedBytes, processingSeconds, storageByteSeconds, createdAt and expiresAt. List accepts cursor and limit (1–100, default 30), orders by ID and returns nextCursor. Retained windows return recordingId, broadcastId, kind, state, startSeconds, endSeconds, wallStart, wallEnd and storedBytes.

PUT buffer-policy accepts { version, policy: { enabled, durationSeconds, maxBytes, consentAcknowledged: true } }. Initial version is zero; a successful mutation increments it. Stale writes return BUFFER_VERSION_CONFLICT. Requests that exceed deployment limits fail with BUFFER_STORAGE_LIMIT. Acknowledged consent is mandatory.

Clip and buffer-policy mutations require Idempotency-Key, scoped to authenticated actor/method/path and checked against the request fingerprint. Repeat the same key and body to obtain the original response; use GET to observe newer state. Conflicting payloads are rejected. Create returns a queued resource, not playable media. Commands that cannot resolve a full interval fail with CLIP_RANGE_EXPIRED, CLIP_RANGE_MISSING, CLIP_RANGE_DISCONTINUOUS or CLIP_WALL_TIME_AMBIGUOUS. CLIP_SOURCE_UNAVAILABLE, CLIP_DURATION_LIMIT and CLIP_CAPACITY describe admission failures. Publication before ready returns CLIP_NOT_READY.

Use GET /v1/recordings/:recordingId/playback for the clip's backing recording, and POST /v1/assets/:assetId/access-grants for playback/download. Optional audience defaults to viewer and requires a published clip. audience: preview requires recordings:create and can preview a ready unpublished clip. All grants expire and remain scoped to the asset, action and current grant epoch. Publication never exposes S3 URLs. Delete revokes grants immediately and removes media asynchronously after lease drain; deleting the original source recording cannot delete a completed independent clip. See cuts, limits and cleanup.

GET /v1/clips/openapi returns a partial OpenAPI 3.1 description for this slice to authenticated management clients when streaming is enabled. Request and response schemas come from shared validators. Its info.version: "v1" identifies the API contract, independently of server and SDK release versions. Existing asset access APIs are documented separately.