{ "variable": [ { "id": "baseUrl", "key": "baseUrl", "type": "string", "name": "string", "value": "https:\/\/studio.upstream.so" } ], "info": { "name": "Upstream.so API", "_postman_id": "ff7dd148-2f20-45c7-b503-486c9ae69cbe", "description": "The Upstream.so API lets you create and run streams, manage your media library, and multistream to every platform \u2014 straight from your own code.", "schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json", "version": "1.0.0" }, "item": [ { "name": "Account", "description": "", "item": [ { "name": "Get the authenticated user", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/user", "query": [], "raw": "{{baseUrl}}\/api\/v1\/user" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns the account that owns the API token used for this request." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":\"a28c5ee5-04c4-4630-86c5-e29081c9ceef\",\"name\":\"Morgan Hirthe\",\"email\":\"dare.emelie@example.com\",\"created_at\":\"2026-08-20T14:55:11+00:00\"}}", "name": "" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" } ] } ] }, { "name": "Streams", "description": "", "item": [ { "name": "List streams", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/streams", "query": [ { "key": "page", "value": "1", "description": "The page number to return. Defaults to 1.", "disabled": false }, { "key": "per_page", "value": "15", "description": "Number of streams per page (1\u2013100). Defaults to 15.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/streams?page=1&per_page=15" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns the streams owned by the authenticated account, paginated. Response\nfields are documented on the \"Get a stream\" endpoint (same resource shape)." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":\"a28c5ee5-8f79-4552-a07a-bc72098cbf63\",\"name\":\"Joseph Bergnaum\",\"description\":null,\"platform\":\"youtube\",\"type\":\"video\",\"url\":\"dQw4w9WgXcQ\",\"status\":\"active\",\"thumbnail_url\":\"https:\\\/\\\/i.ytimg.com\\\/vi\\\/dQw4w9WgXcQ\\\/hqdefault_live.jpg\",\"tags\":[\"lofi\",\"chill\"],\"encoding\":{\"resolution\":\"1920x1080\",\"frame_rate\":\"30\",\"bitrate\":8000,\"audio_bitrate\":128},\"volumes\":{\"main\":70,\"secondary\":30,\"video\":100},\"playback\":{\"mode\":\"loop\",\"video_order\":\"loop\",\"audio_order\":\"loop\",\"default_image_duration\":10},\"transitions\":{\"fade_duration\":2,\"animation_type\":null,\"animation_duration\":null},\"video_fit\":{\"object_fit\":null,\"style\":null,\"background_color\":null},\"schedule\":{\"is_scheduled\":false,\"scheduled_at\":null,\"is_scheduled_end\":false,\"scheduled_end_at\":null,\"repeat_schedule\":false,\"repeat_frequency\":\"daily\",\"mode\":null,\"continuous_start_type\":null,\"continuous_stop_type\":null,\"continuous_stop_at\":null,\"stream_duration_hours\":null,\"stream_duration_minutes\":null,\"break_duration_hours\":null,\"break_duration_minutes\":null,\"preserve_state\":false},\"recording\":null,\"multistream_destinations\":[],\"started_at\":null,\"created_at\":\"2026-08-20T14:55:12+00:00\",\"updated_at\":\"2026-08-20T14:55:12+00:00\"},{\"id\":\"a28c5ee6-3e1b-4769-8c5d-e9e7e1751a34\",\"name\":\"Cleveland Cremin\",\"description\":null,\"platform\":\"youtube\",\"type\":\"video\",\"url\":\"dQw4w9WgXcQ\",\"status\":\"active\",\"thumbnail_url\":\"https:\\\/\\\/i.ytimg.com\\\/vi\\\/dQw4w9WgXcQ\\\/hqdefault_live.jpg\",\"tags\":[\"lofi\",\"chill\"],\"encoding\":{\"resolution\":\"1920x1080\",\"frame_rate\":\"30\",\"bitrate\":8000,\"audio_bitrate\":128},\"volumes\":{\"main\":70,\"secondary\":30,\"video\":100},\"playback\":{\"mode\":\"loop\",\"video_order\":\"loop\",\"audio_order\":\"loop\",\"default_image_duration\":10},\"transitions\":{\"fade_duration\":2,\"animation_type\":null,\"animation_duration\":null},\"video_fit\":{\"object_fit\":null,\"style\":null,\"background_color\":null},\"schedule\":{\"is_scheduled\":false,\"scheduled_at\":null,\"is_scheduled_end\":false,\"scheduled_end_at\":null,\"repeat_schedule\":false,\"repeat_frequency\":\"daily\",\"mode\":null,\"continuous_start_type\":null,\"continuous_stop_type\":null,\"continuous_stop_at\":null,\"stream_duration_hours\":null,\"stream_duration_minutes\":null,\"break_duration_hours\":null,\"break_duration_minutes\":null,\"preserve_state\":false},\"recording\":null,\"multistream_destinations\":[],\"started_at\":null,\"created_at\":\"2026-08-20T14:55:12+00:00\",\"updated_at\":\"2026-08-20T14:55:12+00:00\"}],\"links\":{\"first\":\"\\\/?page=1\",\"last\":\"\\\/?page=1\",\"prev\":null,\"next\":null},\"meta\":{\"current_page\":1,\"from\":1,\"last_page\":1,\"path\":\"\\\/\",\"per_page\":15,\"to\":2,\"total\":2}}", "name": "" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" } ] }, { "name": "Create a stream", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/streams", "query": [], "raw": "{{baseUrl}}\/api\/v1\/streams" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"My 24\\\/7 Lofi Stream\",\"description\":\"Relaxing beats, all day.\",\"platform\":\"youtube\",\"type\":\"video\",\"key\":\"live2\\\/abcd-efgh-ijkl\",\"encoding\":{\"resolution\":\"1920x1080\",\"frame_rate\":30,\"bitrate\":8000,\"audio_bitrate\":128},\"volumes\":{\"main\":70,\"secondary\":30,\"video\":100},\"playback\":{\"mode\":\"loop\",\"video_order\":\"loop\",\"audio_order\":\"loop\",\"default_image_duration\":10},\"transitions\":{\"fade_duration\":2,\"animation_type\":\"fade\",\"animation_duration\":1},\"video_fit\":{\"object_fit\":\"cover\",\"style\":\"blur\",\"background_color\":\"#000000\"},\"schedule\":{\"is_scheduled\":false,\"is_scheduled_end\":false,\"repeat_schedule\":false,\"repeat_frequency\":\"daily\",\"preserve_state\":false},\"recording\":{\"enabled\":false},\"tags\":[\"b\"]}" }, "description": "Creates a stream owned by the authenticated account. The `key` (stream key) is\nrequired for every platform \u2014 for `custom` it must start with rtmp:\/\/ or rtmps:\/\/\nand for `customsrt` with srt:\/\/. Settings groups (volumes, playback, transitions,\nvideo_fit, schedule, recording) are optional and default sensibly when omitted.\n`status` is managed by the start\/stop endpoints and cannot be set here. Returns `201 Created`." }, "response": [ { "header": [], "code": 201, "body": "{\"data\":{\"id\":\"a28c5ee7-182f-46d8-ad94-6ae0efe1a37a\",\"name\":\"Ms. Elisabeth Okuneva\",\"description\":null,\"platform\":\"youtube\",\"type\":\"video\",\"url\":\"dQw4w9WgXcQ\",\"status\":\"installing\",\"thumbnail_url\":\"https:\\\/\\\/i.ytimg.com\\\/vi\\\/dQw4w9WgXcQ\\\/hqdefault_live.jpg\",\"tags\":[\"lofi\",\"chill\"],\"encoding\":{\"resolution\":\"1920x1080\",\"frame_rate\":\"30\",\"bitrate\":8000,\"audio_bitrate\":128},\"volumes\":{\"main\":70,\"secondary\":30,\"video\":100},\"playback\":{\"mode\":\"loop\",\"video_order\":\"loop\",\"audio_order\":\"loop\",\"default_image_duration\":10},\"transitions\":{\"fade_duration\":2,\"animation_type\":null,\"animation_duration\":null},\"video_fit\":{\"object_fit\":null,\"style\":null,\"background_color\":null},\"schedule\":{\"is_scheduled\":false,\"scheduled_at\":null,\"is_scheduled_end\":false,\"scheduled_end_at\":null,\"repeat_schedule\":false,\"repeat_frequency\":\"daily\",\"mode\":null,\"continuous_start_type\":null,\"continuous_stop_type\":null,\"continuous_stop_at\":null,\"stream_duration_hours\":null,\"stream_duration_minutes\":null,\"break_duration_hours\":null,\"break_duration_minutes\":null,\"preserve_state\":false},\"recording\":null,\"multistream_destinations\":[],\"started_at\":null,\"created_at\":\"2026-08-20T14:55:13+00:00\",\"updated_at\":\"2026-08-20T14:55:13+00:00\"}}", "name": "" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"Stream limit reached (3). Upgrade your plan to add more streams.\"}", "name": "Stream limit reached" }, { "header": [], "code": 403, "body": "{\"message\": \"You've used up your streaming time. Upgrade your plan to keep streaming.\"}", "name": "Streaming access exhausted" }, { "header": [], "code": 403, "body": "{\"message\": \"Acting as another account is not supported on the API.\"}", "name": "Acting as another account" }, { "header": [], "code": 422, "body": "{\"message\": \"The key field is required.\", \"errors\": {\"key\": [\"The key field is required.\"]}}", "name": "Validation failed" } ] }, { "name": "Get a stream", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/streams\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/streams\/:id", "variable": [ { "id": "id", "key": "id", "value": "9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e", "description": "The stream's UUID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns a single stream owned by the authenticated account." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":\"a28c5ee7-ecea-48e4-a8f7-1d24ea96c865\",\"name\":\"Morgan Hirthe\",\"description\":null,\"platform\":\"youtube\",\"type\":\"video\",\"url\":\"dQw4w9WgXcQ\",\"status\":\"active\",\"thumbnail_url\":\"https:\\\/\\\/i.ytimg.com\\\/vi\\\/dQw4w9WgXcQ\\\/hqdefault_live.jpg\",\"tags\":[\"lofi\",\"chill\"],\"encoding\":{\"resolution\":\"1920x1080\",\"frame_rate\":\"30\",\"bitrate\":8000,\"audio_bitrate\":128},\"volumes\":{\"main\":70,\"secondary\":30,\"video\":100},\"playback\":{\"mode\":\"loop\",\"video_order\":\"loop\",\"audio_order\":\"loop\",\"default_image_duration\":10},\"transitions\":{\"fade_duration\":2,\"animation_type\":null,\"animation_duration\":null},\"video_fit\":{\"object_fit\":null,\"style\":null,\"background_color\":null},\"schedule\":{\"is_scheduled\":false,\"scheduled_at\":null,\"is_scheduled_end\":false,\"scheduled_end_at\":null,\"repeat_schedule\":false,\"repeat_frequency\":\"daily\",\"mode\":null,\"continuous_start_type\":null,\"continuous_stop_type\":null,\"continuous_stop_at\":null,\"stream_duration_hours\":null,\"stream_duration_minutes\":null,\"break_duration_hours\":null,\"break_duration_minutes\":null,\"preserve_state\":false},\"recording\":null,\"multistream_destinations\":[],\"started_at\":null,\"created_at\":\"2026-08-20T14:55:13+00:00\",\"updated_at\":\"2026-08-20T14:55:13+00:00\"}}", "name": "" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"This action is unauthorized.\"}", "name": "Stream owned by another account" }, { "header": [], "code": 404, "body": "{\"message\": \"Resource not found.\"}", "name": "Stream not found" } ] }, { "name": "Update a stream", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/streams\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/streams\/:id", "variable": [ { "id": "id", "key": "id", "value": "9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e", "description": "The stream's UUID." } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"My 24\\\/7 Lofi Stream\",\"description\":\"Relaxing beats, all day.\",\"platform\":\"youtube\",\"key\":\"live2\\\/abcd-efgh-ijkl\",\"encoding\":{\"resolution\":\"1920x1080\",\"frame_rate\":30,\"bitrate\":8000,\"audio_bitrate\":128},\"volumes\":{\"main\":70,\"secondary\":30,\"video\":100},\"playback\":{\"mode\":\"loop\",\"video_order\":\"loop\",\"audio_order\":\"loop\",\"default_image_duration\":10},\"transitions\":{\"fade_duration\":2,\"animation_type\":\"fade\",\"animation_duration\":1},\"video_fit\":{\"object_fit\":\"cover\",\"style\":\"blur\",\"background_color\":\"#000000\"},\"schedule\":{\"is_scheduled\":false,\"is_scheduled_end\":false,\"repeat_schedule\":false,\"repeat_frequency\":\"daily\",\"preserve_state\":false},\"recording\":{\"enabled\":false},\"tags\":[\"b\"]}" }, "description": "Partially updates a stream owned by the authenticated account \u2014 send only the\nfields you want to change (nested settings objects are merged, not replaced).\n`status` is managed by the start\/stop endpoints and cannot be changed here, and\nmultistream destinations are managed via the Multistreaming endpoints." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":\"a28c5ee8-cf1f-486a-ae0e-c5f38fcf6b25\",\"name\":\"Ms. Elisabeth Okuneva\",\"description\":null,\"platform\":\"youtube\",\"type\":\"video\",\"url\":\"dQw4w9WgXcQ\",\"status\":\"active\",\"thumbnail_url\":\"https:\\\/\\\/i.ytimg.com\\\/vi\\\/dQw4w9WgXcQ\\\/hqdefault_live.jpg\",\"tags\":[\"lofi\",\"chill\"],\"encoding\":{\"resolution\":\"1920x1080\",\"frame_rate\":\"30\",\"bitrate\":8000,\"audio_bitrate\":128},\"volumes\":{\"main\":70,\"secondary\":30,\"video\":100},\"playback\":{\"mode\":\"loop\",\"video_order\":\"loop\",\"audio_order\":\"loop\",\"default_image_duration\":10},\"transitions\":{\"fade_duration\":2,\"animation_type\":null,\"animation_duration\":null},\"video_fit\":{\"object_fit\":null,\"style\":null,\"background_color\":null},\"schedule\":{\"is_scheduled\":false,\"scheduled_at\":null,\"is_scheduled_end\":false,\"scheduled_end_at\":null,\"repeat_schedule\":false,\"repeat_frequency\":\"daily\",\"mode\":null,\"continuous_start_type\":null,\"continuous_stop_type\":null,\"continuous_stop_at\":null,\"stream_duration_hours\":null,\"stream_duration_minutes\":null,\"break_duration_hours\":null,\"break_duration_minutes\":null,\"preserve_state\":false},\"recording\":null,\"multistream_destinations\":[],\"started_at\":null,\"created_at\":\"2026-08-20T14:55:14+00:00\",\"updated_at\":\"2026-08-20T14:55:14+00:00\"}}", "name": "" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"This action is unauthorized.\"}", "name": "Stream owned by another account" }, { "header": [], "code": 404, "body": "{\"message\": \"Resource not found.\"}", "name": "Stream not found" }, { "header": [], "code": 422, "body": "{\"message\": \"The selected encoding.resolution is invalid.\", \"errors\": {\"encoding.resolution\": [\"The selected encoding.resolution is invalid.\"]}}", "name": "Validation failed" } ] }, { "name": "Delete a stream", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/streams\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/streams\/:id", "variable": [ { "id": "id", "key": "id", "value": "9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e", "description": "The stream's UUID." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Permanently deletes a stream owned by the authenticated account (stops any live\nbroadcast and tears down associated resources). Returns an empty 204 response." }, "response": [ { "header": [], "code": 204, "body": "", "name": "Deleted" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"This action is unauthorized.\"}", "name": "Stream owned by another account" }, { "header": [], "code": 404, "body": "{\"message\": \"Resource not found.\"}", "name": "Stream not found" } ] }, { "name": "Start a stream", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/streams\/:stream_id\/start", "query": [], "raw": "{{baseUrl}}\/api\/v1\/streams\/:stream_id\/start", "variable": [ { "id": "stream_id", "key": "stream_id", "value": "9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e", "description": "The stream's UUID." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Starts a stream owned by the authenticated account \u2014 moves it into the `booting`\nstate, after which the platform brings it live (status becomes `active` on its own).\nIdempotent: starting a stream that is already booting or active returns 200 with the\ncurrent stream and makes no change." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":\"a28c5ee9-b0fa-422a-9315-863e4b71762b\",\"name\":\"Morgan Hirthe\",\"description\":null,\"platform\":\"youtube\",\"type\":\"video\",\"url\":\"dQw4w9WgXcQ\",\"status\":\"booting\",\"thumbnail_url\":\"https:\\\/\\\/i.ytimg.com\\\/vi\\\/dQw4w9WgXcQ\\\/hqdefault_live.jpg\",\"tags\":[\"lofi\",\"chill\"],\"encoding\":{\"resolution\":\"1920x1080\",\"frame_rate\":\"30\",\"bitrate\":8000,\"audio_bitrate\":128},\"volumes\":{\"main\":70,\"secondary\":30,\"video\":100},\"playback\":{\"mode\":\"loop\",\"video_order\":\"loop\",\"audio_order\":\"loop\",\"default_image_duration\":10},\"transitions\":{\"fade_duration\":2,\"animation_type\":null,\"animation_duration\":null},\"video_fit\":{\"object_fit\":null,\"style\":null,\"background_color\":null},\"schedule\":{\"is_scheduled\":false,\"scheduled_at\":null,\"is_scheduled_end\":false,\"scheduled_end_at\":null,\"repeat_schedule\":false,\"repeat_frequency\":\"daily\",\"mode\":null,\"continuous_start_type\":null,\"continuous_stop_type\":null,\"continuous_stop_at\":null,\"stream_duration_hours\":null,\"stream_duration_minutes\":null,\"break_duration_hours\":null,\"break_duration_minutes\":null,\"preserve_state\":false},\"recording\":null,\"multistream_destinations\":[],\"started_at\":null,\"created_at\":\"2026-08-20T14:55:14+00:00\",\"updated_at\":\"2026-08-20T14:55:14+00:00\"}}", "name": "" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"This action is unauthorized.\"}", "name": "Stream owned by another account" }, { "header": [], "code": 403, "body": "{\"message\": \"You've used up your streaming time. Upgrade your plan to keep streaming.\"}", "name": "Plan has no streaming access" }, { "header": [], "code": 404, "body": "{\"message\": \"Resource not found.\"}", "name": "Stream not found" }, { "header": [], "code": 409, "body": "{\"message\": \"Stream cannot be started from its current state (installing).\"}", "name": "Not startable from current state" }, { "header": [], "code": 409, "body": "{\"message\": \"Stream was just stopped; wait a few seconds before starting it again.\"}", "name": "Restart cooldown" } ] }, { "name": "Stop a stream", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/streams\/:stream_id\/stop", "query": [], "raw": "{{baseUrl}}\/api\/v1\/streams\/:stream_id\/stop", "variable": [ { "id": "stream_id", "key": "stream_id", "value": "9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e", "description": "The stream's UUID." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Stops a stream owned by the authenticated account \u2014 moves it back into the `paused`\nstate. Idempotent: stopping a stream that is already paused returns 200 with the\ncurrent stream and makes no change." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":\"a28c5eea-8990-4eb0-b573-3692946a6743\",\"name\":\"Morgan Hirthe\",\"description\":null,\"platform\":\"youtube\",\"type\":\"video\",\"url\":\"dQw4w9WgXcQ\",\"status\":\"paused\",\"thumbnail_url\":\"https:\\\/\\\/i.ytimg.com\\\/vi\\\/dQw4w9WgXcQ\\\/hqdefault_live.jpg\",\"tags\":[\"lofi\",\"chill\"],\"encoding\":{\"resolution\":\"1920x1080\",\"frame_rate\":\"30\",\"bitrate\":8000,\"audio_bitrate\":128},\"volumes\":{\"main\":70,\"secondary\":30,\"video\":100},\"playback\":{\"mode\":\"loop\",\"video_order\":\"loop\",\"audio_order\":\"loop\",\"default_image_duration\":10},\"transitions\":{\"fade_duration\":2,\"animation_type\":null,\"animation_duration\":null},\"video_fit\":{\"object_fit\":null,\"style\":null,\"background_color\":null},\"schedule\":{\"is_scheduled\":false,\"scheduled_at\":null,\"is_scheduled_end\":false,\"scheduled_end_at\":null,\"repeat_schedule\":false,\"repeat_frequency\":\"daily\",\"mode\":null,\"continuous_start_type\":null,\"continuous_stop_type\":null,\"continuous_stop_at\":null,\"stream_duration_hours\":null,\"stream_duration_minutes\":null,\"break_duration_hours\":null,\"break_duration_minutes\":null,\"preserve_state\":false},\"recording\":null,\"multistream_destinations\":[],\"started_at\":null,\"created_at\":\"2026-08-20T14:55:15+00:00\",\"updated_at\":\"2026-08-20T14:55:15+00:00\"}}", "name": "" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"This action is unauthorized.\"}", "name": "Stream owned by another account" }, { "header": [], "code": 404, "body": "{\"message\": \"Resource not found.\"}", "name": "Stream not found" }, { "header": [], "code": 409, "body": "{\"message\": \"Stream cannot be stopped from its current state (installing).\"}", "name": "Not stoppable from current state" } ] }, { "name": "List a stream's media queue", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/streams\/:stream_id\/queues\/:type", "query": [ { "key": "page", "value": "1", "description": "The page number to return. Defaults to 1.", "disabled": false }, { "key": "per_page", "value": "15", "description": "Number of items per page (1\u2013100). Defaults to 15.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/streams\/:stream_id\/queues\/:type?page=1&per_page=15", "variable": [ { "id": "stream_id", "key": "stream_id", "value": "9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e", "description": "The stream's UUID." }, { "id": "type", "key": "type", "value": "video", "description": "The queue to read: video, audio, audio-secondary, or external-videos." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns one of a stream's playback queues, paginated and in playback order. The\n`type` segment selects the queue:\n\n- `video` \u2014 the video\/image queue (`selected_videos`)\n- `audio` \u2014 the primary audio queue (`selected_audios`)\n- `audio-secondary` \u2014 the secondary audio queue (`selected_audios_secondary`)\n- `external-videos` \u2014 externally-hosted videos (`selected_external_videos`)\n\nThe first three return Storage-backed media items (identity + metadata; media file\nURLs are intentionally omitted). `external-videos` returns the inline external items,\nincluding the source `url`. An unknown `type` returns 404.\n\nWithin a Storage-backed queue, any entry that no longer resolves \u2014 deleted media,\nmedia still processing, or a file-type mismatch \u2014 is omitted, so the list reflects\nexactly what would play." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": [{\"id\": \"9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e\", \"name\": \"intro.mp4\", \"file_type\": \"video\", \"extension\": \"mp4\", \"duration\": 42.5, \"size\": 10485760, \"title\": null, \"artist\": null, \"album\": null, \"year\": null, \"genre\": null}], \"links\": {\"first\": \"...\", \"last\": \"...\", \"prev\": null, \"next\": null}, \"meta\": {\"current_page\": 1, \"last_page\": 1, \"per_page\": 15, \"total\": 1, \"from\": 1, \"to\": 1}}", "name": "Video queue" }, { "header": [], "code": 200, "body": "{\"data\": [{\"id\": \"65a1f3c0d4e2b\", \"name\": \"Promo\", \"url\": \"https:\/\/example.com\/promo.mp4\", \"file_type\": \"video\", \"thumbnail\": null}], \"links\": {\"first\": \"...\", \"last\": \"...\", \"prev\": null, \"next\": null}, \"meta\": {\"current_page\": 1, \"last_page\": 1, \"per_page\": 15, \"total\": 1, \"from\": 1, \"to\": 1}}", "name": "External video queue" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"This action is unauthorized.\"}", "name": "Stream owned by another account" }, { "header": [], "code": 404, "body": "{\"message\": \"Resource not found.\"}", "name": "Stream or queue type not found" } ] }, { "name": "Add items to a media queue", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/streams\/:stream_id\/queues\/:type", "query": [], "raw": "{{baseUrl}}\/api\/v1\/streams\/:stream_id\/queues\/:type", "variable": [ { "id": "stream_id", "key": "stream_id", "value": "9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e", "description": "The stream's UUID." }, { "id": "type", "key": "type", "value": "video", "description": "The queue: video, audio, audio-secondary, or external-videos." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"items\":[\"6ff8f7f6-1eb3-3525-be4a-3932c805afed\"]}" }, "description": "Appends items to a queue, in order, at the end. For the Storage-backed queues\n(`video`, `audio`, `audio-secondary`) `items` is a list of your own media UUIDs of the\nqueue's type \u2014 still-processing media is accepted (it shows once ready) but failed media\nis rejected; if any id is unavailable the whole request is rejected (422). For\n`external-videos`, `items` is a list of `{url, name}` objects (`.mp4` URLs). An id\/URL\nalready in the queue is skipped \u2014 a queue holds each item at most once. Returns the\nupdated queue." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": [{\"id\": \"9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e\", \"name\": \"intro.mp4\", \"file_type\": \"video\", \"extension\": \"mp4\", \"duration\": 42.5, \"size\": 10485760, \"title\": null, \"artist\": null, \"album\": null, \"year\": null, \"genre\": null}]}", "name": "Updated Storage-backed queue" }, { "header": [], "code": 200, "body": "{\"data\": [{\"id\": \"9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e\", \"name\": \"Promo\", \"url\": \"https:\/\/example.com\/promo.mp4\", \"file_type\": \"video\", \"thumbnail\": null}]}", "name": "Updated external-videos queue" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"This action is unauthorized.\"}", "name": "Stream owned by another account" }, { "header": [], "code": 404, "body": "{\"message\": \"Resource not found.\"}", "name": "Stream not found" }, { "header": [], "code": 422, "body": "{\"message\": \"This media is not available for this queue.\", \"errors\": {\"items.0\": [\"This media is not available for this queue.\"]}}", "name": "An id is unavailable" } ] }, { "name": "Remove an item from a media queue", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/streams\/:stream_id\/queues\/:type\/:mediaId", "query": [], "raw": "{{baseUrl}}\/api\/v1\/streams\/:stream_id\/queues\/:type\/:mediaId", "variable": [ { "id": "stream_id", "key": "stream_id", "value": "9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e", "description": "The stream's UUID." }, { "id": "type", "key": "type", "value": "video", "description": "The queue: video, audio, audio-secondary, or external-videos." }, { "id": "mediaId", "key": "mediaId", "value": "9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e", "description": "The id of the item to remove \u2014 a media UUID for the Storage-backed queues, or the external-video item id for external-videos." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Removes an item from a queue by its id \u2014 a media UUID for the Storage-backed queues, or\nthe inline item id for external-videos. Returns the updated queue, or 404 if that id\nisn't currently in the queue." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": []}", "name": "Updated queue" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"This action is unauthorized.\"}", "name": "Stream owned by another account" }, { "header": [], "code": 404, "body": "{\"message\": \"Resource not found.\"}", "name": "Stream not found or item not in queue" } ] }, { "name": "Reorder a media queue", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/streams\/:stream_id\/queues\/:type\/reorder", "query": [], "raw": "{{baseUrl}}\/api\/v1\/streams\/:stream_id\/queues\/:type\/reorder", "variable": [ { "id": "stream_id", "key": "stream_id", "value": "9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e", "description": "The stream's UUID." }, { "id": "type", "key": "type", "value": "video", "description": "The queue: video, audio, audio-secondary, or external-videos." } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"order\":[\"9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e\"]}" }, "description": "Sets the playback order of a queue (Storage-backed or external-videos). `order` must\ncontain exactly the ids currently visible in the queue \u2014 reorder only reorders; use the\nadd\/remove endpoints to change membership. Returns the reordered queue." }, "response": [ { "header": [], "code": 200, "body": "{\"data\": [{\"id\": \"9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e\", \"name\": \"intro.mp4\", \"file_type\": \"video\", \"extension\": \"mp4\", \"duration\": 42.5, \"size\": 10485760, \"title\": null, \"artist\": null, \"album\": null, \"year\": null, \"genre\": null}]}", "name": "Reordered queue" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"This action is unauthorized.\"}", "name": "Stream owned by another account" }, { "header": [], "code": 404, "body": "{\"message\": \"Resource not found.\"}", "name": "Stream not found" }, { "header": [], "code": 422, "body": "{\"message\": \"The order must contain exactly the items currently in the queue.\", \"errors\": {\"order\": [\"The order must contain exactly the items currently in the queue.\"]}}", "name": "Order isn't the current set" } ] } ] }, { "name": "Multistreaming", "description": "", "item": [ { "name": "List destinations", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/streams\/:stream_id\/destinations", "query": [], "raw": "{{baseUrl}}\/api\/v1\/streams\/:stream_id\/destinations", "variable": [ { "id": "stream_id", "key": "stream_id", "value": "9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e", "description": "The stream's UUID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns the multistream destinations for a stream. Destination stream keys are\nnever exposed." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":\"a28c5eeb-d587-48bc-8c8c-a9e1d5de5bdb\",\"name\":\"aut adipisci\",\"platform\":\"youtube\",\"url\":null,\"status\":\"active\",\"include_in_schedule\":true},{\"id\":\"a28c5eec-83c7-40d6-beee-a6c26d69d5f1\",\"name\":\"deleniti nemo\",\"platform\":\"youtube\",\"url\":null,\"status\":\"active\",\"include_in_schedule\":true}]}", "name": "" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"This action is unauthorized.\"}", "name": "Stream owned by another account" }, { "header": [], "code": 404, "body": "{\"message\": \"Resource not found.\"}", "name": "Stream not found" } ] }, { "name": "Add a destination", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/streams\/:stream_id\/destinations", "query": [], "raw": "{{baseUrl}}\/api\/v1\/streams\/:stream_id\/destinations", "variable": [ { "id": "stream_id", "key": "stream_id", "value": "9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e", "description": "The stream's UUID." } ] }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"Backup YouTube\",\"platform\":\"youtube\",\"url\":\"rtmp:\\\/\\\/a.rtmp.youtube.com\\\/live2\",\"key\":\"live2\\\/abcd-efgh\",\"include_in_schedule\":true,\"status\":\"active\"}" }, "description": "Adds a multistream destination to a stream (max 10 per stream). Returns `201 Created`." }, "response": [ { "header": [], "code": 201, "body": "{\"data\":{\"id\":\"a28c5eed-2350-43a2-9c75-6cf82486195e\",\"name\":\"architecto eius\",\"platform\":\"youtube\",\"url\":null,\"status\":\"active\",\"include_in_schedule\":true}}", "name": "" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"This action is unauthorized.\"}", "name": "Stream owned by another account" }, { "header": [], "code": 404, "body": "{\"message\": \"Resource not found.\"}", "name": "Stream not found" }, { "header": [], "code": 422, "body": "{\"message\": \"This stream already has the maximum of 10 destinations.\"}", "name": "Limit reached" } ] }, { "name": "Update a destination", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/streams\/:stream_id\/destinations\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/streams\/:stream_id\/destinations\/:id", "variable": [ { "id": "stream_id", "key": "stream_id", "value": "9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e", "description": "The stream's UUID." }, { "id": "id", "key": "id", "value": "7c1a9b2e-4ada-bec1-74fd-fdc171b3a21b", "description": "The destination's UUID." } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"Backup YouTube\",\"platform\":\"youtube\",\"url\":\"rtmp:\\\/\\\/a.rtmp.youtube.com\\\/live2\",\"key\":\"live2\\\/abcd-efgh\",\"include_in_schedule\":true,\"status\":\"active\"}" }, "description": "Updates a multistream destination. Send only the fields you want to change." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":\"a28c5eed-d462-4476-a332-4df822319843\",\"name\":\"architecto eius\",\"platform\":\"youtube\",\"url\":null,\"status\":\"active\",\"include_in_schedule\":true}}", "name": "" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"This action is unauthorized.\"}", "name": "Stream owned by another account" }, { "header": [], "code": 404, "body": "{\"message\": \"Resource not found.\"}", "name": "Destination not found" } ] }, { "name": "Remove a destination", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/streams\/:stream_id\/destinations\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/streams\/:stream_id\/destinations\/:id", "variable": [ { "id": "stream_id", "key": "stream_id", "value": "9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e", "description": "The stream's UUID." }, { "id": "id", "key": "id", "value": "7c1a9b2e-4ada-bec1-74fd-fdc171b3a21b", "description": "The destination's UUID." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Deletes a multistream destination. Returns an empty 204 response." }, "response": [ { "header": [], "code": 204, "body": "", "name": "Deleted" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"This action is unauthorized.\"}", "name": "Stream owned by another account" }, { "header": [], "code": 404, "body": "{\"message\": \"Resource not found.\"}", "name": "Destination not found" } ] } ] }, { "name": "Media", "description": "", "item": [ { "name": "Start a media upload", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/media\/uploads", "query": [], "raw": "{{baseUrl}}\/api\/v1\/media\/uploads" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "[]" }, "description": "Returns an upload ticket \u2014 a TUS endpoint plus a short-lived bearer token \u2014 for\nuploading a media file to your library with a resumable (TUS 1.0.0) client.\n\n**Complete, runnable examples** \u2014 Node.js, Python, Go and cURL, each doing the full\nmint \u2192 upload \u2192 poll flow against a ready-to-upload sample clip \u2014 are on GitHub:\n\n\nThe flow has three steps:\n1. Call this endpoint to get `upload_url`, `token` and `expires_at`.\n2. Upload the file to `upload_url` with any TUS 1.0.0 client, sending\n `Authorization: Bearer {token}` and the file name in `Upload-Metadata`. To place\n the file in a folder you own, send its UUID as a `Folder-Id` header \u2014 the server\n validates ownership and silently ignores an unknown or foreign id (the file then\n lands at the library root). When the upload finishes, the response carries the new\n file's id in the `storage-id` header.\n3. Poll `GET \/api\/v1\/media\/{id}` until `is_processing` is `false`.\n\nOne token drives many uploads \u2014 sequential or concurrent \u2014 for its full 24-hour life;\nit is validated per request, not consumed. Because it is single-active per account\n(minting a new one, here or via the web app, revokes the previous), mint **once** and\nreuse it for a batch \u2014 minting per file would revoke your other in-flight uploads.\n\nExample with tus-js-client:\n\n```js\nimport * as tus from 'tus-js-client'\n\nconst { upload_url, token } = ticket.data \/\/ from POST \/api\/v1\/media\/uploads\nconst upload = new tus.Upload(file, {\n endpoint: upload_url,\n headers: { Authorization: `Bearer ${token}`, 'Folder-Id': folderId }, \/\/ Folder-Id optional\n metadata: { name: file.name },\n onAfterResponse: (req, res) => {\n const id = res.getHeader('storage-id')\n if (id) console.log('media id:', id) \/\/ then poll GET \/api\/v1\/media\/{id}\n },\n onError: console.error,\n})\nupload.start()\n```\n\n`upload_url` points at your account's default (closest) region. The token is valid on\nevery regional upload server, so you may instead upload to the nearest:\n- Europe \u2014 `https:\/\/e.upstream.so\/api\/upload\/`\n- America \u2014 `https:\/\/a.upstream.so\/api\/upload\/`\n- Asia \u2014 `https:\/\/i.upstream.so\/api\/upload\/`" }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"upload_url\":\"https:\/\/e.upstream.so\/api\/upload\/\",\"token\":\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\"expires_at\":\"2026-06-27T12:00:00+00:00\",\"folder_id\":null}}", "name": "Upload ticket" }, { "header": [], "code": 401, "body": "{\"message\":\"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\":\"This action is unauthorized.\"}", "name": "Account has no active subscription or trial" }, { "header": [], "code": 422, "body": "{\"message\":\"The folder_id must be a folder you own.\",\"errors\":{\"folder_id\":[\"The folder_id must be a folder you own.\"]}}", "name": "folder_id is not a folder you own" } ] }, { "name": "List media files", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/media", "query": [ { "key": "type", "value": "audio", "description": "Filter by file type: `video`, `audio`, `image`, or `font`.", "disabled": false }, { "key": "search", "value": "intro", "description": "Case-insensitive match against the file name. Must not be greater than 255 characters.", "disabled": false }, { "key": "folder_id", "value": "root", "description": "A folder UUID to list that folder's files, or `root` for files not in any folder.", "disabled": false }, { "key": "page", "value": "1", "description": "The page number to return. Defaults to 1.", "disabled": false }, { "key": "per_page", "value": "15", "description": "Number of files per page (1\u2013100). Defaults to 15.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/media?type=audio&search=intro&folder_id=root&page=1&per_page=15" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns the media files owned by the authenticated account, newest first,\npaginated. Filter by `type`, by a `search` term matched against the file name,\nor by `folder_id` (a folder's UUID, or `root` for files not in any folder)." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":\"a28c5eee-39bc-4924-ae62-4a70f81db72e\",\"name\":\"architecto\",\"file_type\":\"audio\",\"extension\":\"skt\",\"size\":629000564,\"duration\":null,\"resolution\":null,\"title\":null,\"artist\":null,\"album\":null,\"year\":null,\"genre\":null,\"folder_id\":null,\"is_processing\":false},{\"id\":\"a28c5eee-b752-4175-b622-58ad4057a303\",\"name\":\"ab\",\"file_type\":\"video\",\"extension\":\"lasxml\",\"size\":3498,\"duration\":null,\"resolution\":null,\"title\":null,\"artist\":null,\"album\":null,\"year\":null,\"genre\":null,\"folder_id\":null,\"is_processing\":false}],\"links\":{\"first\":\"\\\/?page=1\",\"last\":\"\\\/?page=1\",\"prev\":null,\"next\":null},\"meta\":{\"current_page\":1,\"from\":1,\"last_page\":1,\"path\":\"\\\/\",\"per_page\":15,\"to\":2,\"total\":2}}", "name": "" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 422, "body": "{\"message\": \"The folder_id must be a valid UUID or \\\"root\\\".\", \"errors\": {\"folder_id\": [\"The folder_id must be a valid UUID or \\\"root\\\".\"]}}", "name": "Invalid filter" } ] }, { "name": "Get a media file", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/media\/:media_id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/media\/:media_id", "variable": [ { "id": "media_id", "key": "media_id", "value": "9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e", "description": "The media file's UUID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns a single media file owned by the authenticated account." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":\"a28c5eef-3910-45c8-9e5a-137c63a3a656\",\"name\":\"aut\",\"file_type\":\"audio\",\"extension\":\"wmx\",\"size\":1031881,\"duration\":null,\"resolution\":null,\"title\":null,\"artist\":null,\"album\":null,\"year\":null,\"genre\":null,\"folder_id\":null,\"is_processing\":false}}", "name": "" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"This action is unauthorized.\"}", "name": "File owned by another account" }, { "header": [], "code": 404, "body": "{\"message\": \"Resource not found.\"}", "name": "File not found" } ] }, { "name": "Update a media file", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/media\/:media_id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/media\/:media_id", "variable": [ { "id": "media_id", "key": "media_id", "value": "9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e", "description": "The media file's UUID." } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"intro.mp4\",\"title\":\"My Title\",\"artist\":\"My Artist\",\"album\":\"My Album\",\"year\":\"2026\",\"genre\":\"Lofi\"}" }, "description": "Updates a media file owned by the authenticated account. Send only the fields you\nwant to change. `name` renames any file; the audio metadata fields (`title`,\n`artist`, `album`, `year`, `genre`) apply to audio files only and are rejected on\nother types." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":\"a28c5eef-bf08-4fae-bc8b-38fdca9c68d1\",\"name\":\"architecto\",\"file_type\":\"audio\",\"extension\":\"skt\",\"size\":629000564,\"duration\":null,\"resolution\":null,\"title\":null,\"artist\":null,\"album\":null,\"year\":null,\"genre\":null,\"folder_id\":null,\"is_processing\":false}}", "name": "" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"This action is unauthorized.\"}", "name": "File owned by another account" }, { "header": [], "code": 404, "body": "{\"message\": \"Resource not found.\"}", "name": "File not found" }, { "header": [], "code": 422, "body": "{\"message\": \"Metadata can only be edited for audio files.\", \"errors\": {\"title\": [\"Metadata can only be edited for audio files.\"]}}", "name": "Metadata on a non-audio file" } ] }, { "name": "Delete a media file", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/media\/:media_id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/media\/:media_id", "variable": [ { "id": "media_id", "key": "media_id", "value": "9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e", "description": "The media file's UUID." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Deletes a media file owned by the authenticated account. The file is removed from\nevery stream's queues and deleted from storage. Returns an empty 204 response." }, "response": [ { "header": [], "code": 204, "body": "", "name": "Deleted" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"This action is unauthorized.\"}", "name": "File owned by another account" }, { "header": [], "code": 404, "body": "{\"message\": \"Resource not found.\"}", "name": "File not found" } ] } ] }, { "name": "Folders", "description": "", "item": [ { "name": "List folders", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/folders", "query": [ { "key": "parent_id", "value": "root", "description": "A folder UUID to list its direct children, or `root` for top-level folders.", "disabled": false }, { "key": "page", "value": "1", "description": "The page number to return. Defaults to 1.", "disabled": false }, { "key": "per_page", "value": "15", "description": "Number of folders per page (1\u2013100). Defaults to 15.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/folders?parent_id=root&page=1&per_page=15" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns the folders owned by the authenticated account, newest first, paginated.\nFilter by `parent_id` (a folder's UUID for its direct children, or `root` for\ntop-level folders)." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":\"a28c5ef1-c98b-4f50-808b-6de14028b4a1\",\"name\":\"Morgan Hirthe\",\"parent_id\":null},{\"id\":\"a28c5ef2-2021-4034-8143-56a00424ea54\",\"name\":\"Mr. Oswald Koch\",\"parent_id\":null}],\"links\":{\"first\":\"\\\/?page=1\",\"last\":\"\\\/?page=1\",\"prev\":null,\"next\":null},\"meta\":{\"current_page\":1,\"from\":1,\"last_page\":1,\"path\":\"\\\/\",\"per_page\":15,\"to\":2,\"total\":2}}", "name": "" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 422, "body": "{\"message\": \"The parent_id must be a valid UUID or \\\"root\\\".\", \"errors\": {\"parent_id\": [\"The parent_id must be a valid UUID or \\\"root\\\".\"]}}", "name": "Invalid filter" } ] }, { "name": "Create a folder", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/folders", "query": [], "raw": "{{baseUrl}}\/api\/v1\/folders" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"Clips\"}" }, "description": "Creates a folder owned by the authenticated account. Omit `parent_id` (or send null)\nfor a top-level folder, or pass an owned folder's UUID to nest it. Returns `201 Created`." }, "response": [ { "header": [], "code": 201, "body": "{\"data\":{\"id\":\"a28c5ef2-841d-4228-86e1-cc01cea18175\",\"name\":\"Ms. Audra Crooks II\",\"parent_id\":null}}", "name": "" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"This action is unauthorized.\"}", "name": "Account has no streaming plan" }, { "header": [], "code": 403, "body": "{\"message\": \"Acting as another account is not supported on the API.\"}", "name": "Acting as another account" }, { "header": [], "code": 422, "body": "{\"message\": \"The name field is required.\", \"errors\": {\"name\": [\"The name field is required.\"]}}", "name": "Invalid input" } ] }, { "name": "Move files", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/folders\/move-files", "query": [], "raw": "{{baseUrl}}\/api\/v1\/folders\/move-files" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"media_ids\":[\"6ff8f7f6-1eb3-3525-be4a-3932c805afed\"]}" }, "description": "Moves the given media files into a folder, or to the root. Pass `folder_id` (an owned\nfolder's UUID) to move them into that folder, or omit it (or send null) to move them\nto the root. Every file \u2014 and the destination folder \u2014 must be owned by the\nauthenticated account. Returns an empty 204." }, "response": [ { "header": [], "code": 204, "body": "", "name": "Moved" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"Acting as another account is not supported on the API.\"}", "name": "Acting as another account" }, { "header": [], "code": 422, "body": "{\"message\": \"One or more of the media files do not belong to you.\", \"errors\": {\"media_ids\": [\"One or more of the media files do not belong to you.\"]}}", "name": "A file is not owned by the caller" }, { "header": [], "code": 422, "body": "{\"message\": \"The selected folder is invalid.\", \"errors\": {\"folder_id\": [\"The selected folder is invalid.\"]}}", "name": "The destination folder is not owned by the caller" } ] }, { "name": "Get a folder", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/folders\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/folders\/:id", "variable": [ { "id": "id", "key": "id", "value": "9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e", "description": "The folder's UUID." } ] }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns a single folder owned by the authenticated account. List a folder's\nchildren with `GET \/folders?parent_id={id}`." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":\"a28c5ef2-e9e4-49e8-88f3-533f31e89e55\",\"name\":\"Morgan Hirthe\",\"parent_id\":null}}", "name": "" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"This action is unauthorized.\"}", "name": "Folder owned by another account" }, { "header": [], "code": 404, "body": "{\"message\": \"Resource not found.\"}", "name": "Folder not found" } ] }, { "name": "Update a folder", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/folders\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/folders\/:id", "variable": [ { "id": "id", "key": "id", "value": "9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e", "description": "The folder's UUID." } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"Renamed clips\"}" }, "description": "Updates a folder owned by the authenticated account. Send `name` to rename, and\/or\n`parent_id` to move it (an owned folder's UUID to nest it, or null to move it to the\nroot). A folder can't be moved into itself or one of its descendants." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":\"a28c5ef3-430e-4271-8b75-f13593544f00\",\"name\":\"Ms. Audra Crooks II\",\"parent_id\":null}}", "name": "" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"This action is unauthorized.\"}", "name": "Folder owned by another account" }, { "header": [], "code": 404, "body": "{\"message\": \"Resource not found.\"}", "name": "Folder not found" }, { "header": [], "code": 422, "body": "{\"message\": \"A folder cannot be moved into itself or its descendants.\", \"errors\": {\"parent_id\": [\"A folder cannot be moved into itself or its descendants.\"]}}", "name": "Cyclic move" } ] }, { "name": "Delete a folder", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/folders\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/folders\/:id", "variable": [ { "id": "id", "key": "id", "value": "9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e", "description": "The folder's UUID." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Deletes a folder owned by the authenticated account. Its subfolders are deleted too,\nand any files inside are moved to the root (not deleted). Returns an empty 204." }, "response": [ { "header": [], "code": 204, "body": "", "name": "Deleted" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"This action is unauthorized.\"}", "name": "Folder owned by another account" }, { "header": [], "code": 404, "body": "{\"message\": \"Resource not found.\"}", "name": "Folder not found" } ] } ] }, { "name": "Tags", "description": "", "item": [ { "name": "List tags", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/tags", "query": [], "raw": "{{baseUrl}}\/api\/v1\/tags" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns all the tags owned by the authenticated account, ordered by name (not\npaginated \u2014 the full set is small and is meant to populate a tag picker). Tag\nnames can be assigned to streams via the stream create\/update endpoints." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":[{\"id\":\"a28c5ef0-4e61-430b-9f57-eeef691b1028\",\"name\":\"aut\",\"color\":\"#a11e59\",\"icon\":\"X\"},{\"id\":\"a28c5ef0-9fef-47f3-bf1f-94ca6948e295\",\"name\":\"enim\",\"color\":\"#a453cd\",\"icon\":\"X\"}]}", "name": "" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" } ] }, { "name": "Create a tag", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/tags", "query": [], "raw": "{{baseUrl}}\/api\/v1\/tags" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"lofi\",\"color\":\"#3366FF\",\"icon\":\"music\"}" }, "description": "Creates a tag owned by the authenticated account. Tag names are unique per account.\nReturns `201 Created`." }, "response": [ { "header": [], "code": 201, "body": "{\"data\":{\"id\":\"a28c5ef1-04c3-4599-9cdd-dfc33530549a\",\"name\":\"architecto\",\"color\":\"#66e353\",\"icon\":\"X\"}}", "name": "" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 422, "body": "{\"message\": \"The name has already been taken.\", \"errors\": {\"name\": [\"The name has already been taken.\"]}}", "name": "Validation failed" } ] }, { "name": "Update a tag", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/tags\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/tags\/:id", "variable": [ { "id": "id", "key": "id", "value": "9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e", "description": "The tag's UUID." } ] }, "method": "PATCH", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"name\":\"lofi\",\"color\":\"#3366FF\",\"icon\":\"music\"}" }, "description": "Updates a tag owned by the authenticated account. Send only the fields you want to change." }, "response": [ { "header": [], "code": 200, "body": "{\"data\":{\"id\":\"a28c5ef1-5e95-4f52-9466-506d1d8bfc16\",\"name\":\"architecto\",\"color\":\"#66e353\",\"icon\":\"X\"}}", "name": "" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"This action is unauthorized.\"}", "name": "Tag owned by another account" }, { "header": [], "code": 404, "body": "{\"message\": \"Resource not found.\"}", "name": "Tag not found" }, { "header": [], "code": 422, "body": "{\"message\": \"The name has already been taken.\", \"errors\": {\"name\": [\"The name has already been taken.\"]}}", "name": "Validation failed" } ] }, { "name": "Delete a tag", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/tags\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/tags\/:id", "variable": [ { "id": "id", "key": "id", "value": "9b2e7c1a-4f3d-4a8b-9c2e-1f3d4a8b9c2e", "description": "The tag's UUID." } ] }, "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Deletes a tag owned by the authenticated account and removes it from any streams.\nReturns an empty 204 response." }, "response": [ { "header": [], "code": 204, "body": "", "name": "Deleted" }, { "header": [], "code": 401, "body": "{\"message\": \"Unauthenticated.\"}", "name": "Missing or invalid token" }, { "header": [], "code": 403, "body": "{\"message\": \"This action is unauthorized.\"}", "name": "Tag owned by another account" }, { "header": [], "code": 404, "body": "{\"message\": \"Resource not found.\"}", "name": "Tag not found" } ] } ] } ], "auth": { "type": "bearer", "bearer": [ { "key": "Authorization", "type": "string" } ] } }