Watch
For testing only.
This endpoint is a proof-of-concept and not yet in active use.
Watch session data added via this API is not integrated with the rest of the platform.
Watch endpoints replace the upsertWatchHistory mutation.
Summary
When a video is played with an API consumer video player, the API consumer must:
- Establish a globally unique watch ID (UUID recommended) to be sent will all request for the watch session;
- Send an initial
POST /watch/startrequest; - Send periodic (every 5 seconds recommended)
POST /watch/updaterequests; - Determine at the end of the session if the viewer completed the video; and
- Send a final
POST /watch/stoprequest.
POST /watch/start
Purpose
Start a new watch session.
This endpoint should be called each time a video is started in an API consumer video player.
Payload
Type
JSON in body.
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
deviceId | Yes | String | ID of device the watch is happening on. |
sessionId | Yes | String | Globally unique watch ID (UUID recommended). Must be generated by consumer and used for subsequent requests for the watch session. |
startSeconds | No | Integer | How many seconds in to the video the watch is starting from (default: 0). |
stationId | Yes | UUID | ID of the station associated with the request. |
videoId | Yes | UUID | ID of the video being watched. |
viewerId | Yes | UUID | ID of the viewer watching the video. |
Responses
- 204 No Content
- 400 Bad Request
- 401 Unauthorized
- 405 Method Not Allowed
- 500 Internal Server Error
Watch session has been started.
Invalid body payload.
API user key is invalid or the API user is disabled.
Unsupported HTTP method was used for the request.
API server error.
POST /watch/update
Purpose
Update the video position of a watch session.
This endpoint should only be called after POST /watch/start to update a known watch session.
Recommended call interval: every 5 seconds.
Payload
Type
JSON in body.
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
deviceId | Yes | String | ID of device the watch is happening on. |
currentSeconds | Yes | Integer | Current video position (in seconds) of the watch session. |
sessionId | Yes | String | Globally unique watch ID sent with POST /watch/start. |
Responses
- 204 No Content
- 400 Bad Request
- 401 Unauthorized
- 405 Method Not Allowed
- 405 Method Not Allowed
- 500 Internal Server Error
Watch session has been updated.
Invalid body payload.
API user key is invalid or the API user is disabled.
Active watch session not found (see: POST /watch/start).
Unsupported HTTP method was used for the request.
API server error.
POST /watch/stop
Purpose
Stop a watch session.
This endpoint should only be called after POST /watch/start to stop a known watch session.
Payload
Type
JSON in body.
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
deviceId | Yes | String | ID of device the watch is happening on. |
contentCompleted | Yes | Boolean | Whether the video watched in the session is considered complete. |
currentSeconds | Yes | Integer | Final video position (in seconds) of the watch session. |
sessionId | Yes | String | Globally unique watch ID sent with POST /watch/start. |
Responses
- 204 No Content
- 400 Bad Request
- 401 Unauthorized
- 405 Method Not Allowed
- 405 Method Not Allowed
- 500 Internal Server Error
Watch session has been ended.
Invalid body payload.
API user key is invalid or the API user is disabled.
Active watch session not found (see: POST /watch/start).
Unsupported HTTP method was used for the request.
API server error.