CDPGuidesSupport

Videos

Create and manage hosted videos, upload MP4 or WebM files, replace transcripts, and retrieve account-wide or per-video engagement analytics through the REST API.

Create, retrieve, update, and delete hosted videos. The API also provides an upload target for original video files, transcript management, and engagement analytics.

Uploads and processing

POST /rest/v1/videos creates a video record and returns an upload object containing a temporary direct-upload URL and the required mimeType. The create request accepts MP4 and WEBM original files only. A video title defaults to New Video when omitted.

To replace the source for an existing video without changing its ID, title, embed URL, or analytics, call POST /rest/v1/videos/{id}/upload with mimeType, then PUT the new file to the returned URL using that exact content type. The response has the same { url, mimeType } shape as the create upload target.

Video processing occurs after the original file is uploaded. GET /rest/v1/videos/{id} includes resolvedValues, which reports the current video, poster, and transcript availability and includes their URLs when available. Poll that endpoint after either upload target is used until the processed assets are available.

Transcripts

GET /rest/v1/videos/{id}/transcript returns the current WebVTT transcript in content, or null when no transcript is available. PUT /rest/v1/videos/{id}/transcript replaces the transcript with a JSON request containing format (VTT or SRT) and content. Transcript content must contain between 1 and 1,000,000 characters. SRT content is normalized to WebVTT before it is saved.

Important: Transcript text is available wherever the video is embedded. Do not include protected health information (PHI) or other confidential information in a transcript.

Analytics

GET /rest/v1/videos/analytics returns account-wide, per-video engagement metrics for an inclusive UTC date range. It uses limit and offset pagination, with a default limit of 50 and a maximum of 100. total is the number of rows returned through the current offset, not the total number of matching videos. Date windows may be up to 90 days.

The optional videoId query parameter filters these metrics to one video. It accepts a video UUID; omitting it returns account-wide results. A video with no matching analytics returns an empty items array.

GET /rest/v1/videos/{id}/analytics returns an engagement time series for one video. The default granularity is DAILY; use HOURLY for windows up to 14 days. Daily windows may be up to 90 days. Both analytics endpoints require from and to as inclusive UTC calendar days in YYYY-MM-DD format.

GET/rest/v1/videos

GET
/rest/v1/videos

Authorization

apiKey
AuthorizationBearer <token>

Ours Privacy API key

In: header

Query Parameters

limit?|

Maximum number of items to return. Defaults to 25; values below 1 are clamped to 1 and values above 100 are clamped to 100.

cursor?string

Opaque pagination cursor from pagination.nextCursor in the previous response. Do not decode or modify it. Malformed cursors return 400 Bad Request.

nameContains?string

Case-insensitive substring match on the video title.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/rest/v1/videos"
{  "entities": [    {      "id": "string",      "accountId": "string",      "createdAt": "string",      "updatedAt": "string",      "type": "Video",      "name": "string",      "description": "string",      "duration": 0,      "width": 0,      "height": 0,      "hasVideoUpload": true,      "captionsUpdatedAt": "string",      "captionsUpdatedByName": "string"    }  ],  "pagination": {    "nextCursor": "string",    "hasMore": true  }}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}

POST/rest/v1/videos

POST
/rest/v1/videos
*object

Authorization

apiKey
AuthorizationBearer <token>

Ours Privacy API key

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/rest/v1/videos" \  -H "Content-Type: application/json" \  -d '{    "mimeType": "MP4"  }'
{  "id": "string",  "accountId": "string",  "createdAt": "string",  "updatedAt": "string",  "type": "Video",  "name": "string",  "description": "string",  "duration": 0,  "width": 0,  "height": 0,  "hasVideoUpload": true,  "captionsUpdatedAt": "string",  "captionsUpdatedByName": "string",  "upload": {    "url": "http://example.com",    "mimeType": "MP4"  }}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}

GET/rest/v1/videos/{id}

GET
/rest/v1/videos/{id}

Authorization

apiKey
AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/rest/v1/videos/string"
{  "id": "string",  "accountId": "string",  "createdAt": "string",  "updatedAt": "string",  "type": "Video",  "name": "string",  "description": "string",  "duration": 0,  "width": 0,  "height": 0,  "hasVideoUpload": true,  "captionsUpdatedAt": "string",  "captionsUpdatedByName": "string",  "resolvedValues": {    "videoStatus": {      "posterExists": true,      "outputExists": true,      "outputIsCurrent": true,      "transcriptionExists": true    },    "mediaConvertJob": {      "status": "string",      "percentComplete": 0    },    "posterUrl": "string",    "videoUrl": "string",    "vttUrl": "string"  }}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}

PATCH/rest/v1/videos/{id}

PATCH
/rest/v1/videos/{id}
*object

Authorization

apiKey
AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/rest/v1/videos/string" \  -H "Content-Type: application/json" \  -d '{}'
{  "id": "string",  "accountId": "string",  "createdAt": "string",  "updatedAt": "string",  "type": "Video",  "name": "string",  "description": "string",  "duration": 0,  "width": 0,  "height": 0,  "hasVideoUpload": true,  "captionsUpdatedAt": "string",  "captionsUpdatedByName": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}

DELETE/rest/v1/videos/{id}

DELETE
/rest/v1/videos/{id}

Authorization

apiKey
AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/rest/v1/videos/string"
{  "id": "string",  "deleted": true}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}

POST/rest/v1/videos/{id}/upload

POST
/rest/v1/videos/{id}/upload
*object

Authorization

apiKey
AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/rest/v1/videos/string/upload" \  -H "Content-Type: application/json" \  -d '{    "mimeType": "MP4"  }'
{  "url": "http://example.com",  "mimeType": "MP4"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}

GET/rest/v1/videos/{id}/transcript

GET
/rest/v1/videos/{id}/transcript

Authorization

apiKey
AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/rest/v1/videos/string/transcript"
{  "content": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}

PUT/rest/v1/videos/{id}/transcript

PUT
/rest/v1/videos/{id}/transcript
*object

Authorization

apiKey
AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/rest/v1/videos/string/transcript" \  -H "Content-Type: application/json" \  -d '{    "format": "SRT",    "content": "string"  }'
{  "id": "string",  "accountId": "string",  "createdAt": "string",  "updatedAt": "string",  "type": "Video",  "name": "string",  "description": "string",  "duration": 0,  "width": 0,  "height": 0,  "hasVideoUpload": true,  "captionsUpdatedAt": "string",  "captionsUpdatedByName": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}

GET/rest/v1/videos/analytics

GET
/rest/v1/videos/analytics

Authorization

apiKey
AuthorizationBearer <token>

Ours Privacy API key

In: header

Query Parameters

from*string

Inclusive UTC start day in YYYY-MM-DD format.

Match^\d{4}-\d{2}-\d{2}$
to*string

Inclusive UTC end day in YYYY-MM-DD format.

Match^\d{4}-\d{2}-\d{2}$
videoId?string

Filter analytics to one video by its ID. Omit to include all account videos.

Formatuuid
limit?integer

Maximum number of video rows to return. Defaults to 50.

Range1 <= value <= 100
offset?|

Zero-based row offset. This report is an intentional offset-pagination exception.

Range0 <= value

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/rest/v1/videos/analytics?from=string&to=string"
{  "items": [    {      "videoId": "string",      "videoTitle": "string",      "videoUrl": "string",      "videoStarts": 0,      "uniqueViewers": 0,      "avgWatchTimeSeconds": 0,      "completionRate": 0,      "avgVideoDurationSeconds": 0    }  ],  "total": 0,  "hasMore": true}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}

GET/rest/v1/videos/{id}/analytics

GET
/rest/v1/videos/{id}/analytics

Authorization

apiKey
AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Query Parameters

from*string

Inclusive UTC start day in YYYY-MM-DD format.

Match^\d{4}-\d{2}-\d{2}$
to*string

Inclusive UTC end day in YYYY-MM-DD format.

Match^\d{4}-\d{2}-\d{2}$
granularity?string

Bucket size. Defaults to DAILY; HOURLY supports windows of up to 14 days.

Value in

  • "DAILY"
  • "HOURLY"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/rest/v1/videos/string/analytics?from=string&to=string"
{  "items": [    {      "dateTime": "string",      "videoStarts": 0,      "uniqueViewers": 0,      "completions": 0,      "completionRate": 0    }  ]}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}
{  "error": "string",  "details": "string"}

How is this guide?

Short Links

Previous Page

Video Channels

Next Page