Watch Progress

An optional endpoint that syncs the user's watch position back to your service, so progress follows them across devices.

Advertise the progress keyword in your manifest'scapabilities to mount this route. It requires theprogress.write scope and — like every write — a credential you can map to a user account (see the write model).

PUT/videos/{id}/progress

curl -X PUT "https://api.example.com/vcp/v1/videos/vid_88213/progress" \
  -H "VCP-Service-Token: vcps_a81f42..." \
  -H "Authorization: Bearer vcpa_71be02..." \
  -H "Content-Type: application/json" \
  -d '{ "position": 981.5, "duration": 1440, "watched": false }'

# -> 204 No Content

import requests

API = "https://api.example.com/vcp/v1"
HEADERS = {
    "VCP-Service-Token": "vcps_a81f42...",
    "Authorization": "Bearer vcpa_71be02...",
}

resp = requests.put(f"{API}/videos/vid_88213/progress", headers=HEADERS,
                    json={"position": 981.5, "duration": 1440, "watched": False})
resp.raise_for_status()  # 204 No Content

require "rest-client"
require "json"

API = "https://api.example.com/vcp/v1"
HEADERS = {
  "VCP-Service-Token" => "vcps_a81f42...",
  "Authorization" => "Bearer vcpa_71be02...",
  content_type: :json
}

RestClient.put("#{API}/videos/vid_88213/progress",
               { position: 981.5, duration: 1440, watched: false }.to_json,
               HEADERS)
# -> 204 No Content

const API = 'https://api.example.com/vcp/v1'
const HEADERS = {
  'VCP-Service-Token': 'vcps_a81f42...',
  'Authorization': 'Bearer vcpa_71be02...',
  'Content-Type': 'application/json',
}

const resp = await fetch(API + '/videos/vid_88213/progress', {
  method: 'PUT',
  headers: HEADERS,
  body: JSON.stringify({ position: 981.5, duration: 1440, watched: false }),
})
if (resp.status !== 204) throw new Error('progress write failed: ' + resp.status)

Field	Description
`position`	Current playback position in seconds (JSON number).
`duration`	The video's duration as the client knows it, in seconds.
`watched`	`true` marks the video fully watched.

The response is 204 No Content. Progress is a simple last-write-wins value: it's a PUT, safe to retry blindly, with no versioning. Clients debounce writes — roughly every 30 seconds of playback plus on pause and exit — so expect a modest, steady write volume rather than one write per second.