Media streams API

Base path: /api/streams

A stream is an uploaded media file plus its transformed variants (thumbnails, resized images, transcoded audio/video). The route handles the HTTP surface — parsing, status codes, and building the upload URLs — while storage and persistence live behind the streams repository.

All endpoints require an authenticated session and operate on the current user’s streams.

List

  • GET /api/streams — list the user’s streams.
    • Query: from (offset, default 0), size (default 20, max 100), nextToken (opaque cursor for token-paginated backends), filter[finalized] (true/1), filter[accept] (comma-separated media types).
    • When the backend paginates by token, the next cursor is returned in the X-Next-Token response header.

Create

  • POST /api/streams/add — register a stream and receive its upload URLs.
    • Body: { "filename": string, "mediaType": string, "size": number, "mode": "server" | "client" }.
    • Response: { "stream": Stream, "meta": { "chunkSize": number, "urls": { "upload": string, "finalize": string } } }.

The returned upload URL depends on the mode: a single-shot server upload, a client-handled upload, or a multipart URL when the file is chunked.

Upload flow

Drive the upload against the URLs returned by add:

  • POST /api/streams/upload/:stream_id — upload the file (server mode).
  • POST /api/streams/upload/:stream_id/handle — register a client-side upload (client mode).
  • POST /api/streams/upload/:stream_id/part — upload one part of a multipart/chunked upload.
  • POST /api/streams/upload/:stream_id/finalize — finalize the upload; the backend then generates the transformed variants.
  • POST /api/streams/prepare — prepare a stream ahead of upload.

Read and manage

  • GET /api/streams/:id — fetch a single stream and its variants.
  • DELETE /api/streams/:id — soft-delete a stream (404 when not found).
  • GET /api/streams/:id/thumbnail — the stream’s thumbnail.
  • GET /api/streams/:id/view — a viewable rendition of the stream.