Merge pull request #346 from apivideo/add-live-stream-completed-endpoint

Add live stream completed endpoint
apivideo · Jul 23, 2024 · fcc07c2 · fcc07c2
2 parents db2f193 + f12fc37
commit fcc07c2
Show file tree

Hide file tree

Showing 2 changed files with 109 additions and 0 deletions.
diff --git a/live-streaming/working-with-live-streams.md b/live-streaming/working-with-live-streams.md
@@ -12,6 +12,7 @@ When working with live streams, you will want to retrieve details about them, up
 
 - [Retrieve a live stream](/reference/api/Live-Streams#retrieve-live-stream)
 - [Update a live stream](/reference/api/Live-Streams#update-a-live-stream)
+- [Complete a live stream](/reference/api/Live-Streams#complete-a-live-stream)
 - [Delete a live stream](/reference/api/Live-Streams#delete-a-list-stream)
 
 ## Choose an api.video client
@@ -301,6 +302,22 @@ You can update live stream details from your dashboard if you don't want to retr
 
 5. You can change the title of your live stream, upload a thumbnail, and associate a player ID on this screen. When you're done, click **Save**.
 
+## Complete a live stream
+
+You can request the API to complete a live stream that is currently running. This operation is asynchronous and the live stream will stop after a few seconds. 
+
+The API adds the `EXT-X-ENDLIST` tag to the live stream's HLS manifest. This stops the live stream on the player and also stops the recording of the live stream. The API keeps the incoming connection from the streamer open for at most 1 minute, which can be used to terminate the stream.
+
+```curl
+curl --request PUT \
+     --url https://ws.api.video/live-streams/li400mYKSgQ6xs7taUeSaEKr/complete \
+     --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NDI4MTQxNDUuMjE2Mzc2LCJuYmYiOjE2NDI4MTQxNDUuMjE2Mzc2LCJleHAiOjE2NDI4MTc3NDUuMjE2Mzc2LCJwcm9qZWN0SWQiOiJwclJ6SUpKQTdCTHNxSGpTNDVLVnBCMSJ9.GSDqqMzBxo-wOwl9IVbOnzevm8A6LSyaR5kxCWUdkEneSU0kIdoNfhwmXZBq5QWpVa-0GIT8JR59W6npNO-ayhaXmV3LA6EQpvv0mHd_dAhg3N8T96eC0ps0YIrkmw0_Oe6iRgEDI-wJ9nc6tQWi9ybbMHi1LDBjxW4rbFlq7G59C1QZGabd14QO7uqAUUSNqHC1l42z_m7BTK1AhFiBEXmMcfW7X0VmGcaEUy7NiNda8rmq_nrdvkxgN8KHguXzxMsw_4GE_d0eQwHcZvS1q-FebI6b8AoqpoltFOZvUACCrfXH_D_UPshHuJM3apXbD2dg_zQicc8oWBHVGiobLQ'
+```
+
+<Callout pad="2" type="info">
+api.video recommends that you use this endpoint to properly complete a live stream.
+</Callout>
+
 ## Delete a live stream
 
 You can delete a live stream by sending in a DELETE request using the unique ID for the live stream. The code sample looks like this:

diff --git a/openapi.yaml b/openapi.yaml
@@ -6952,6 +6952,98 @@ paths:
             code: |
               // First install the api client: https://github.com/apivideo/api.video-swift-client#getting-started
               // Documentation: https://github.com/apivideo/api.video-swift-client/blob/main/docs/LiveStreamsAPI.md#deleteThumbnail
+  '/live-streams/{liveStreamId}/complete':
+    put:
+      tags:
+        - Live Streams
+      summary: Complete a live stream
+      description: |
+        Request the completion of a live stream that is currently running. This operation is asynchronous and the live stream will stop after a few seconds. 
+
+        The API adds the `EXT-X-ENDLIST` tag to the live stream's HLS manifest. This stops the live stream on the player and also stops the recording of the live stream. The API keeps the incoming connection from the streamer open for at most 1 minute, which can be used to terminate the stream.
+      operationId: PUT_live-streams-liveStreamId-complete
+      parameters:
+        - name: liveStreamId
+          in: path
+          description: The unique ID for the live stream you want to complete.
+          required: true
+          style: simple
+          explode: false
+          schema:
+            type: string
+          example: vi4k0jvEUuaTdRAEjQ4Jfrgz
+      responses:
+        '202':
+          headers:
+            X-RateLimit-Limit:
+              schema:
+                type: integer
+              description: The request limit per minute.
+            X-RateLimit-Remaining:
+              schema:
+                type: integer
+              description: The number of available requests left for the current time window.
+            X-RateLimit-Retry-After:
+              schema:
+                type: integer
+              description: The number of seconds left until the current rate limit window resets.
+          description: Accepted
+        '404':
+          headers:
+            X-RateLimit-Limit:
+              schema:
+                type: integer
+              description: The request limit per minute.
+            X-RateLimit-Remaining:
+              schema:
+                type: integer
+              description: The number of available requests left for the current time window.
+            X-RateLimit-Retry-After:
+              schema:
+                type: integer
+              description: The number of seconds left until the current rate limit window resets.
+          description: Not Found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/not-found'
+              examples:
+                response:
+                  value:
+                    type: 'https://docs.api.video/reference/resource-not-found'
+                    title: The requested resource was not found.
+                    name: liveStreamId
+                    status: 404
+        '429':
+          headers:
+            X-RateLimit-Limit:
+              schema:
+                type: integer
+              description: The request limit per minute.
+            X-RateLimit-Remaining:
+              schema:
+                type: integer
+              description: The number of available requests left for the current time window.
+            X-RateLimit-Retry-After:
+              schema:
+                type: integer
+              description: The number of seconds left until the current rate limit window resets.
+          description: Too Many Requests
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/too-many-requests'
+              examples:
+                Too many requests:
+                  value:
+                    type: 'https://docs.api.video/reference/too-many-requests'
+                    title: Too many requests.
+                    status: 429
+      security:
+        - apiKey: []
+      x-client-action: update
+      x-doctave:
+        code-samples:
   '/videos/{videoId}/captions/{language}':
     get:
       tags: