API docs by Redocly

Truvid API (1.0.0)

Download OpenAPI specification:

License: Truvid

Truvid API

Categories

Get Categories

List available categories, including relevant details such as name, unique ID, and any associated properties. The response will include various attributes and configuration settings for each category.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "categories": [
    ]
}

Content Targeting

List Targeted Content in Publisher's Domains

Get a list of targeted content in publisher's domains. Content targeting allows content providers to target a specified video to play on a specified URL. This endpoint returns a list of targeted videos and their designated URLs. It is possible to filter this list using query parameters.

Authorizations:
bearerAuth
query Parameters
organization_id
integer

Filter by the ID of the organization of the publisher that uses this content.

search
string

Search the URL field.

sort_by
string
Enum: "url" "create_date"

How results should be sorted.

sort_order
string
Enum: "asc" "desc"

Sort Order

video_id
string

Filter by a specific video ID.

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "content_targeting": [
    ]
}

Create Video URL Association

Create an association between a video and a URL to target specific content. Content targeting allows content providers to specify which video should play first in a player located at a given URL. Use this endpoint to target a video to run as the first video in a player at the specified URL.

Authorizations:
bearerAuth
Request Body schema: application/json
required
organization_id
integer

Unique identifier of the organization of the publisher that uses this content

url
required
string

URL of the targeted content

video_id
required
string

Unique identifier for the video that is being targeted

overwrite
boolean

Indicates if pairing the URL with another video should overwrite an existing pairing. A value of true means the existing pairing will be overwritten, while false means it will not.

Responses

Request samples

Content type
application/json
{
  • "organization_id": 0,
  • "url": "string",
  • "video_id": "string",
  • "overwrite": true
}

Response samples

Content type
application/json
{
  • "id": 0
}

Get Video URL Association by video id

Authorizations:
bearerAuth
path Parameters
video_id
required
string

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Delete Video URL Association

Remove the association between a video and a specified URL. This endpoint deletes the specified content targeting item, ensuring the targeted video no longer plays on the specified URL.

Authorizations:
bearerAuth
path Parameters
id
required
string

The ID of the targeted URL. This ID can be retrieved using the GET /content/targeting/url endpoint.

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Countries

Get Countries

List available countries, including relevant details such as name, code, and unique ID. The response will include various properties and configuration settings for each country.

Responses

Response samples

Content type
application/json
{
  • "countries": [
    ]
}

Folder

Get Folder Details

Retrieve details of a specific folder by its unique identifier. The response includes the folder's properties and configuration settings.

Authorizations:
bearerAuth
query Parameters
folder_id
required
integer

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "organization_id": 0,
  • "name": "string",
  • "create_date": "string",
  • "number_of_videos": 0,
  • "videos": [
    ]
}

Create Folder

Create a new folder in the system. The request should include the necessary details for the new folder. The response confirms the creation and provides the folder's unique identifier.

Authorizations:
bearerAuth
Request Body schema: application/json
required
organization_id
integer

Unique identifier of the organization associated with the folder

folder_name
string <= 128 characters

Name of folder. Maximum length is 128 characters.

Responses

Request samples

Content type
application/json
{
  • "organization_id": 0,
  • "folder_name": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "organization_id": 0,
  • "name": "string",
  • "create_date": "string",
  • "number_of_videos": 0,
  • "videos": [
    ]
}

Update Folder

Update the details of an existing folder. The request should include the folder ID and the fields to be updated. The response confirms the update by returning the folder's updated details.

Authorizations:
bearerAuth
Request Body schema: application/json
required
folder_id
required
integer

Unique identifier of the folder in which the video is stored. If not specified in the request, the default folder is "General". The list of possible folders and their IDs can be found in the GET /folders endpoint.

folder_name
required
string <= 128

Name of folder. Maximum length is 128 characters.

Responses

Request samples

Content type
application/json
{
  • "folder_id": 0,
  • "folder_name": "string"
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "organization_id": 0,
  • "name": "string",
  • "create_date": "string",
  • "number_of_videos": 0,
  • "videos": [
    ]
}

Delete Folder

Delete an existing folder by its unique ID. The request should include the folder ID. The response confirms the deletion and provides the status of the operation.

Authorizations:
bearerAuth
path Parameters
id
required
string

Folder ID

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

List Folders

Retrieve a list of folders based on the provided query parameters. The response will include various properties and configuration settings of the folders.

Authorizations:
bearerAuth
query Parameters
organization_id
integer

Search for folders of a specific Organization ID.

page_number
integer

The result's page number. For example, if you set the results_per_page to 20, in the first request set the page_number to 1 and you will receive the first 20 results. And in the second call request set the page_number to 2 to retrieve the next 20 results.

sort_by
string
Enum: "name" "create_date"

How results should be sorted. Possible values - name - alphabetical order of the name of the folder. create_date - the date in which the folder was created.

sort_order
string
Enum: "asc" "desc"

The order in which the results are sorted. asc - ascending; desc - descending

results_per_page
integer [ 1 .. 20 ]

The number of results to display per page.

search
string

Search folder by name. The search results prioritize newer folders and the matching degree to the search string.

list_only
boolean

Get only metadata about all the folders

Responses

Response samples

Content type
application/json
{
  • "folders": [
    ],
  • "total": 0
}

Languages

Get Languages

List available languages, including relevant details such as name, code, and unique ID. The response will include various attributes and configuration settings for each language.

Responses

Response samples

Content type
application/json
{
  • "languages": [
    ]
}

Organization User

Get Access Details for a User

Get access details in order to use the API with

Request Body schema: application/json
required
email
required
string

Email address associated with the user account

password
required
string

Password associated with the user account

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "tokens": {
    },
  • "user": {
    }
}

Refresh Access Details of a User

Obtain a new access token by providing the refresh token from a previous login session. This endpoint allows users to refresh their access without logging in again, ensuring continued access to the system. The request requires the refresh token in the body, and the response will include the new access token along with other token-related details.

Authorizations:
bearerAuth
Request Body schema: application/json
required
refresh_token
required
string

Token used to request a new access token, typically when the current access token has expired

Responses

Request samples

Content type
application/json
{
  • "refresh_token": "string"
}

Response samples

Content type
application/json
{
  • "tokens": {
    },
  • "user": {
    }
}

Report

Create Report

Create a report with the specified parameters. The response will include the report data and relevant configuration settings.

Authorizations:
bearerAuth
query Parameters
include_totals
boolean

Add a formatted totals column

Request Body schema: application/json
required
organization_id
integer

Organization ID associated with the report

report_name
required
string
Enum: "console_publisher_truvid_report" "console_publisher_content_report" "console_content_content_report" "console_accounts_account_report"

Name of the report

start_date
required
string

Start date in the format YYYY-MM-DDTHH:mm

end_date
required
string

End date in the format YYYY-MM-DDTHH:mm

timezone
string
Default: "UTC"

Time zone. Default is UTC.

max_results
integer <= 500
Default: 100

Maximum number of results in the report. Default is 100, maximum is 500.

download
boolean
Default: false

Enables retrieval of the complete dataset in a downloadable file. Default is false.

Array of strings

Array of columns

Array of objects

Array of filters

sort_field
string

Field by which results should be sorted

sort_direction
string
Enum: "asc" "desc"

Order in which the results are sorted. Possible values are asc or desc.

group_by
string
Enum: "hour" "day" "month"

How the results should be grouped. Possible values are hour, day, or month.

Responses

Request samples

Content type
application/json
{
  • "organization_id": 0,
  • "report_name": "console_publisher_truvid_report",
  • "start_date": "string",
  • "end_date": "string",
  • "timezone": "UTC",
  • "max_results": 100,
  • "download": false,
  • "columns": [
    ],
  • "filters": [
    ],
  • "sort_field": "string",
  • "sort_direction": "asc",
  • "group_by": "hour"
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "columns": [
    ],
  • "sorting": {
    }
}

Get Report Columns

Get the columns that can be selected for display in a report. The response will include information about each column's properties and settings.

Authorizations:
bearerAuth
query Parameters
report_name
string
Enum: "console_publisher_truvid_report" "console_publisher_content_report" "console_content_content_report" "console_accounts_account_report"

Responses

Response samples

Content type
application/json
{
  • "column_name": "string",
  • "orderable": true,
  • "title": "string",
  • "is_default": true,
  • "searchable": true
}

Video

Get Video Details

Retrieve the full details of the specified video by its unique ID. The response will include various properties and configuration settings of the video.

Authorizations:
bearerAuth
query Parameters
video_id
required
string

Truvid's ID number for the video

guid
required
string

External ID (Guid) of the video

Responses

Response samples

Content type
application/json
{
  • "video": {
    },
  • "tags": [
    ]
}

Upload Video

Add a video to Truvid's library. If the video is added from a public URL, specify this URL in the source_url attribute. If the video is added from a local machine (i.e., not a public URL), follow these steps:

  1. Send a request to the /video/request_upload endpoint (no attributes required).
  2. Use the signed_url from the /video/request_upload response to upload the video using the PUT method.
  3. After uploading the video, use the public_url from the /video/request_upload response as the source_url in the POST /video request.

The /video/request_upload endpoint response includes two parameters:

signed_url: This URL is an endpoint and should be used to send the file to Truvid using the PUT method.

public_url: After the video has been uploaded to the URL in the signed_url, submit the POST /video request, adding the URL in the public_url to the source_url attribute.

Authorizations:
bearerAuth
Request Body schema: application/json
required
source_url
required
string

Public URL for the video or the URL from the public_url attribute of the POST /video/request_upload endpoint response.

title
required
string <= 200 characters

Title of the video. Maximum length is 200 characters.

description
string <= 5000 characters

Video description. Maximum length is 5000 characters.

private
boolean
Default: false

Indicates if the video is set as private. A value of true means the video is private and can only be seen by users from the same organization, while false means the video is public. Default is false.

language_id
integer
Default: 9

Unique identifier associated with the language of the video. Default is 9.

pricing_model
string
Default: "rev_share"
Enum: "rev_share" "free"

Pricing model used to monetize the video. Possible values are free (not monetized) and rev_share (monetized with a revenue share model). Default is rev_share.

folder_id
integer

ID of the folder in which the video is stored. If not specified in the request, the default folder is "General". The list of possible folders and their IDs can be found in the GET /folders endpoint.

categories
required
Array of integers [ 1 .. 5 ] items

Array of categories associated with the video. Possible categories can be found in the GET /categories endpoint. Minimum is 1. Maximum is 5.

guid
string <= 1000 characters

Globally unique identifier (GUID) associated with the video. The identifier originates from the external system from which the video has been uploaded to Truvid. Maximum length is 1000 characters.

Array of objects

Set an array of custom clickthrough URLs for the video. These URLs will appear at a specified time in the video. Clicking on the URL will navigate to the specified destination.

thumbnail_url
string

Thumbnail URL that is specified in the response of the POST: /thumbnail/custom endpoint

tags
Array of strings

Array of tags associated with the video. The video will be automatically added to playlists with matching tags and the auto_updated feature enabled.

source_type
string
Value: "mrss"

Type of the video's source. Possible value is MRSS.

source_id
integer

Unique identifier of the video's source

countries_allow
Array of strings

List of countries that the video is allowed to played at

countries_disallow
Array of strings

List of countries that the video is not allowed to played at

Responses

Request samples

Content type
application/json
{
  • "source_url": "string",
  • "title": "string",
  • "description": "string",
  • "private": false,
  • "language_id": 9,
  • "pricing_model": "rev_share",
  • "folder_id": 0,
  • "categories": [
    ],
  • "guid": "string",
  • "clickthrough_urls": [
    ],
  • "thumbnail_url": "string",
  • "tags": [
    ],
  • "source_type": "mrss",
  • "source_id": 0,
  • "countries_allow": [
    ],
  • "countries_disallow": [
    ]
}

Response samples

Content type
application/json
{
  • "video_id": "string"
}

Update Video

Update the specified video's details. The request should include the video ID and the fields to be updated. The response will confirm the update by returning the video's updated details.

Authorizations:
bearerAuth
Request Body schema: application/json
required
video_id
required
string

Unique identifier for the video

title
string <= 200 characters

Title of the video. Maximum length is 200 characters.

description
string <= 5000 characters

Video description. Maximum length is 5000 characters.

video_tags
Array of arrays <= 5 characters

Assign this video with up to 5 tags.

private
boolean
Default: false

Indicates if the video is set as private. A value of true means the video is private and can only be seen by users from the same organization, while false means the video is public. Default is false.

language_id
integer
Default: 9

Unique identifier associated with the language of the video. Default is 9.

pricing_model
string
Default: "rev_share"
Enum: "rev_share" "free"

Pricing model used to monetize the video. Possible values are free (not monetized) and rev_share (monetized with a revenue share model). Default is rev_share.

folder_id
integer

ID of the folder in which the video is stored. If not specified in the request, the default folder is "General". The list of possible folders and their IDs can be found in the GET /folders endpoint.

categories
Array of integers [ 1 .. 5 ] items

Array of categories associated with the video. Possible categories can be found in the GET /categories endpoint. Minimum is 1. Maximum is 5.

guid
string <= 1000 characters

Globally unique identifier (GUID) associated with the video. The identifier originates from the external system from which the video has been uploaded to Truvid. Maximum length is 1000 characters.

Array of objects

Set an array of custom clickthrough URLs for the video. These URLs will appear at a specified time in the video. Clicking on the URL will navigate to the specified destination.

thumbnail_url
string

Set a new thumbnail for the video

countries_allow
Array of strings

List of countries that the video is allowed to played at

countries_disallow
Array of strings

List of countries that the video is not allowed to played at

Responses

Request samples

Content type
application/json
{
  • "video_id": "string",
  • "title": "string",
  • "description": "string",
  • "video_tags": [ ],
  • "private": false,
  • "language_id": 9,
  • "pricing_model": "rev_share",
  • "folder_id": 0,
  • "categories": [
    ],
  • "guid": "string",
  • "clickthrough_urls": [
    ],
  • "thumbnail_url": "string",
  • "countries_allow": [
    ],
  • "countries_disallow": [
    ]
}

Response samples

Content type
application/json
{
  • "video_id": "string",
  • "organization_id": 0,
  • "organization_name": "string",
  • "folder_id": 0,
  • "title": "string",
  • "description": "string",
  • "upload_date": "string",
  • "last_modified": "string",
  • "duration_in_ms": 0,
  • "status": "string",
  • "pricing_model": "string",
  • "language_id": 0,
  • "private": true,
  • "formats": [
    ],
  • "guid": "string",
  • "categories": [
    ],
  • "thumb_ext": "string",
  • "thumbnails": [
    ],
  • "source": {
    },
  • "countries_allow": [
    ],
  • "countries_disallow": [
    ]
}

Delete Video

Delete the specified video by its unique ID. The request should include the video ID. The response will confirm the deletion and provide the status of the operation.

Authorizations:
bearerAuth
path Parameters
video_id
required
string

The Id of the video in Truvid's library.

Responses

List Videos

List videos based on the provided query parameters. The response will include various properties and configuration settings of the videos.

Authorizations:
bearerAuth
query Parameters
organization_id
integer

The ID of the organization associated with the video. Only videos belonging to this organization will be returned.

search
string

Search video by title. The search results prioritize newer videos and the matching degree to the search string.

folder_id
integer

Search by the folder ID.

categories
Array of integers

Search by an array of category IDs.

min_duration
integer

The minimum duration of videos, specified in milliseconds.

max_duration
integer

The maximum duration of videos, specified in milliseconds

pricing_model
string
Value: "rev_share"

Search by the pricing model. Possible values - free - the video is not monetized; rev_share - the video is monetized with a revenue share model.

languages
Array of integers

Search by the ID of the language associated with the video.

tag_ids
Array of integers

Search videos by tag IDs.

sort_by
string
Enum: "upload_date" "title" "duration_in_ms" "language_id" "private" "pricing_model"

How results should be sorted. Possible values - upload_date - sorts by the date the video was uploaded. title - alphabetical order of the title. duration_in_ms - the video's duration in milliseconds

sort_order
string
Enum: "asc" "desc"

The order in which the results are sorted. asc - ascending; desc - descending.

page_number
integer

The result's page number. For example, if you set the results_per_page to 20, in the first request set the page_number to 1 and you will receive the first 20 results. And in the second call request set the page_number to 2 to retrieve the next 20 results.

results_per_page
integer [ 1 .. 20 ]

The number of results to display per page

package_ids
Array of integers

Array of integers used to filter content based on package IDs

guid
string

Search videos by GUID

show_public
boolean

Filters videos based on their privacy settings for a specific user and organization ID. Possible values: true - the video is set to public; false - the video is not set to private. If the organization ID is not provided, the operation will not work as expected

time_range
string
Enum: "last_h" "last_24h" "last_7d" "last_30d" "last_1y"

Search videos based on the time range in which they were uploaded. See list of possible values in the example.

status
Array of strings

Search videos based on their status.

source_type
string

Search videos based on source type

source_id
integer

Search videos based on source id

is_vertical
boolean

Search videos based on proportion

Responses

Response samples

Content type
application/json
{
  • "videos": [
    ],
  • "total_videos": 0
}