Introduction
OpenVeo Publish defines its own Web Service endpoints. Web Service authentication is documented in OpenVeo project.
Endpoints
Videos
Get videos.
GET WEB_SERVICE_URL/publish/videos
Name | Type | Required | Default | Details |
---|---|---|---|---|
query | String | No | - | To search on both videos title and description |
useSmartSearch | Number | No | 1 | 1 to use a more advanced search mechanism, 0 to use a simple search based on a regular expression |
states | String/Array | No | - | To filter videos by state |
dateStart | String/Number | No | - | To get videos after or equal to a date (in any format supported by JavaScript Date object) |
dateEnd | String/Number | No | - | To get videos before or equal to a date (in any format supported by JavaScript Date object) |
categories | String/Array | No | - | To filter videos by category |
groups | String/Array | No | - | To filter videos by group |
user | String/Array | No | - | To filter videos by user |
sortBy | String | No | date | To sort videos by either title, description, date, state, views or category |
sortOrder | String | No | desc | Sort order (either asc or desc) |
page | Number | No | 0 | The expected page |
limit | Number | No | 10 | To limit the number of videos per page |
properties | Object | No | - | A list of custom properties with the property id as the key and the expected property value as the value (e.g. properties[property1Id]=property1Value) Date time properties accept either timestamps or literal dates |
include | Array | No | - | The list of fields to include from returned videos |
exclude | Array | No | - | The list of fields to exclude from returned videos. Ignored if include is also specified |
HTTP Status Code | Details |
---|---|
200 | Got the list of videos |
500 | An error occured on the server side |
400 | Wrong list of parameters |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"entities" : [
{
"id" : 1444396683105, // Id of the video
"state" : 12, // Video state
"date" : 1425916390000, // Date in timestamp
"type" : "vimeo", // Video associated platform
"errorCode" : -1, // Video error code or -1 if no error
"category" : "", // Video category
"properties" : { // Video custom properties
"1444809111034": { // Custom property id
"id" : 1444809111034, // Custom property id
"name" : "Property name", // Custom property name
"description" : "Property description", // Custom property description
"type" : "text", // Custom property type
"value" : "Property value" // Custom property value
}
...
},
"link" : "http://openveo.local/publish/video/1444396683105", // Path to play the video
"mediaId" : "141902178", // Video id on video platform
"available" : true, // Indicates if video is available or is being encoded
"thumbnail" : "http://openveo-cdn.local/1444396683105/thumbnail.jpg",
"title" : "Video title",
"leadParagraph" : "Video lead paragraph",
"description" : "Video description",
"chapters" : [ // Chapters
{
"name" : "Chapter 1", // Chapter name
"description" : "Chapter 1", // Chapter description
"value" : 0.04 // Chapter timecode in percent (percentage of the video)
},
...
],
"tags" : [ // Tags
{
"name" : "Tag 1", // Tag name
"description" : "Tag 1 description", // Tag description
"value" : 0.3, // Tag timecode in percent (percentage of the video)
"file" : { // Tag associated file
"mimeType" : "video/mp4",
"url" : "http://openveo-cdn.local/path/to/ressource/video.mp4",
"originalName" : "original-name.mp4",
"fileName" : "name.mp4",
"size" : 102458
}
},
...
],
"cut" : [ // Cut information (begin and end)
{
"type" : "begin", // Cut type
"value" : 0 // Begin timecode (percentage of the media)
},
{
"type" : "end", // Cut type
"value" : 0.9 // End timecode (percentage of the media)
}
],
"timecodes" : [ // Video synchronized images
{
"image" : {
"large" : "http://openveo-cdn.local/1440175380631/slide_00000.jpeg", // Large image
"small" : {
"url" : "http://openveo-cdn.local/1440175380631/points-of-interest-images.jpg", // Sprite containing the small image
"x" : 0, // x coordinate of the small image inside the sprite
"y" : 0 // y coordinate of the small image inside the sprite
}
},
"timecode" : 0 // Timecode when to display the image (in ms)
},
...
]
}
],
"pagination": {
"limit": 1,
"page": 0,
"pages": 2,
"size": 2
}
}
Videos can be in different states:
- 0 : The video is on error
- 1 : The video is waiting to be treated
- 2 : The video is copying
- 3 : The video package is extracting
- 4 : The video package is validating
- 5 : The video package is preparing
- 6 : The video is waiting for manual upload
- 7 : The video is uploading to the video platform
- 8 : The video is being configured on the video platform
- 9 : The video timecodes are being saved
- 10 : The video synchronized images are being saved
- 11 : The video is uploaded and ready but unpublished
- 12 : The video is uploaded, ready and published
- 13 : The video thumbnail is generated
- 14 : The video metadatas are being retrieved
- 15 : The video is defragmenting
Get a video.
GET WEB_SERVICE_URL/publish/videos/{video_id}
Name | Type | Required | Default | Details |
---|---|---|---|---|
include | Array | No | - | The list of fields to include from returned video |
exclude | Array | No | - | The list of fields to exclude from returned video. Ignored if include is also specified |
HTTP Status Code | Details |
---|---|
200 | Got the video |
500 | An error occured on the server side |
400 | The id of the video is missing |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
404 | Video not found |
{
"entity" : {
"id" : 1444396683105, // Id of the video
"state" : 12, // Video state
"date" : 1425916390000, // Date in timestamp
"type" : "vimeo", // Video associated platform
"errorCode" : -1, // Video error code or -1 if no error
"category" : "", // Video category
"properties" : { // Video custom properties
"1444809111034": { // Custom property id
"id" : 1444809111034, // Custom property id
"name" : "Property name", // Custom property name
"description" : "Property description", // Custom property description
"type" : "text", // Custom property type
"value" : "Property value" // Custom property value
},
...
},
"packageType" : "tar", // Initialize package type (either tar or mp4)
"link" : "http://openveo.local/publish/video/1444396683105", // Path to play the video
"mediaId" : "141902178", // Video id on video platform
"available" : true, // Indicates if video is available or is being encoded
"thumbnail" : "http://openveo-cdn.local//1444396683105/thumbnail.jpg",
"title" : "Video title",
"leadParagraph" : "Video lead paragraph",
"description" : "Video description",
"chapters" : [ // Chapters
{
"name" : "Chapter 1", // Chapter name
"description" : "Chapter 1", // Chapter description
"value" : 0.04 // Chapter timecode in percent (percentage of the video)
},
...
],
"tags" : [ // Tags
{
"name" : "Tag 1", // Tag name
"description" : "Tag 1 description", // Tag description
"value" : 0.3, // Tag timecode in percent (percentage of the video)
"file" : { // Tag associated file
"mimeType" : "video/mp4",
"url" : "http://openveo-cdn.local/path/to/ressource/video.mp4",
"originalName" : "original-name.mp4",
"fileName" : "name.mp4",
"size" : 102458
}
},
...
],
"cut" : [ // Cut information (begin and end)
{
"type" : "begin", // Cut type
"value" : 0 // Begin timecode (percentage of the media)
},
{
"type" : "end", // Cut type
"value" : 0.9 // End timecode (percentage of the media)
}
],
"timecodes" : [ // Video synchronized images
{
"image" : {
"large" : "http://openveo-cdn.local/1440175380631/slide_00000.jpeg", // Large image
"small" : {
"url" : "http://openveo-cdn.local/1440175380631/points-of-interest-images.jpg", // Sprite containing the small image
"x" : 0, // x coordinate of the small image inside the sprite
"y" : 0 // y coordinate of the small image inside the sprite
}
},
"timecode" : 0 // Timecode when to display the image (in ms)
},
...
]
}
}
Delete videos.
DELETE WEB_SERVICE_URL/publish/videos/{video_id}
With {video_id} a comma separated list of video ids to delete.
HTTP Status Code | Details |
---|---|
200 | The videos have been deleted |
500 | An error occured on the server side |
400 | Missing the video ids |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"total": 42
}
Add video.
POST WEB_SERVICE_URL/publish/videos
Expects a multipart/form-data body containing:
Name | Type | Required | Default | Details |
---|---|---|---|---|
file | File | Yes | - | The video file |
thumbnail | File | No | - | The video thumbnail |
info | Object | Yes | - | The video metadata |
info.title | String | Yes | - | The video title |
info.properties | Object | No | - | The custom properties of the video with the keys as custom property ids and values as custom property values |
info.category | String | No | - | The id of the category the video belongs to |
info.date | String | No | - | The date of the video (in any format supported by JavaScript Date object) |
info.leadParagraph | String | No | - | The video lead paragraph |
info.description | String | No | - | The video description |
info.groups | Array | No | - | The list of content groups (ids) the video belongs to |
info.platform | String | No | - | The platform to upload the file to. If no platform is specified the video will be in "Waiting for upload" state. Platform could be one of the platforms defined in videoPlatformConf.json configuration file (either vimeo, wowza, youtube or local) |
info.user | String | No | - | The id of the OpenVeo user to use as the video owner (default is the super admin id) |
HTTP Status Code | Details |
---|---|
200 | The video has been added |
500 | An error occured on the server side |
400 | Missing body |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"id": 42
}
Publish videos.
POST WEB_SERVICE_URL/publish/videos/{video_id}/publish
With {video_id} a comma separated list of video ids to publish.
HTTP Status Code | Details |
---|---|
200 | The videos have been published |
500 | An error occured on the server side |
400 | Missing the video ids |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"total": 42
}
Unpublish videos.
POST WEB_SERVICE_URL/publish/videos/{video_id}/unpublish
With {video_id} a comma separated list of video ids to unpublish.
HTTP Status Code | Details |
---|---|
200 | The videos have been unpublished |
500 | An error occured on the server side |
400 | Missing the video ids |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"total": 42
}
Properties
Get custom properties.
GET WEB_SERVICE_URL/publish/properties
Name | Type | Required | Default | Details |
---|---|---|---|---|
query | String | No | - | To search on both properties name and description |
useSmartSearch | Number | No | 1 | 1 to use a more advanced search mechanism, 0 to use a simple search based on a regular expression |
types | String/Array | No | - | To filter properties by type |
sortBy | String | No | name | To sort properties by either name or description |
sortOrder | String | No | desc | Sort order (either asc or desc) |
page | Number | No | 0 | The expected page |
limit | Number | No | 10 | To limit the number of properties per page |
include | Array | No | - | The list of fields to include from returned properties |
exclude | Array | No | - | The list of fields to exclude from returned properties. Ignored if include is also specified |
HTTP Status Code | Details |
---|---|
200 | Got the list of properties |
500 | An error occured on the server side |
400 | Wrong list of parameters |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"entities": [
{
"id": "4JMy6htjpe",
"name": "Property name",
"description": "Property description",
"type": "text"
},
{
"id": "4JMy6htjpe",
"name": "Property name",
"description": "Property description",
"type": "list",
"values": ["value1", "value2"]
}
],
"pagination": {
"limit": 1,
"page": 0,
"pages": 2,
"size": 2
}
}
Get a property.
GET WEB_SERVICE_URL/publish/properties/{property_id}
With {property_id} the id of the property to retrieve.
Name | Type | Required | Default | Details |
---|---|---|---|---|
include | Array | No | - | The list of fields to include from returned property |
exclude | Array | No | - | The list of fields to exclude from returned property. Ignored if include is also specified |
HTTP Status Code | Details |
---|---|
200 | Got the property |
500 | An error occured on the server side |
400 | The id of the property is missing |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
404 | Property not found |
{
"entity": {
"id": "NyiBTYjTe",
"name": "Property name",
"description": "Property description",
"type": "text"
}
}
Get the list of properties types.
GET WEB_SERVICE_URL/publish/propertiesTypes
HTTP Status Code | Details |
---|---|
200 | Got the list of properties types |
{
"types": [
"text",
"list",
"boolean"
]
}
Add custom properties.
PUT WEB_SERVICE_URL/publish/properties
Expects an Array of objects containing:
Name | Type | Required | Default | Details |
---|---|---|---|---|
name | String | Yes | - | The custom property name |
description | String | Yes | - | The custom property description |
type | String | Yes | - | The custom property type (either text, list, or boolean) |
values | Array | No | - | The custom property values if type is list |
HTTP Status Code | Details |
---|---|
200 | The properties have been added |
500 | An error occured on the server side |
400 | Wrong PUT parameters |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"entities": [
{
"id": "4JMy6htjpe",
"name": "Property name",
"description": "Property description",
"type": "list",
"values": ["value1", "value2"]
},
...
]
}
Update a property.
POST WEB_SERVICE_URL/publish/properties/{property_id}
With {property_id} the id of the property to update.
Name | Type | Required | Default | Details |
---|---|---|---|---|
name | String | No | - | The custom property name |
description | String | No | - | The custom property description |
type | String | No | - | The custom property type (either text, list, or boolean) |
values | Array | No | - | The custom property values if type is list |
HTTP Status Code | Details |
---|---|
200 | The property has been updated |
500 | An error occured on the server side |
400 | Missing the property id |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"total": 1
}
Delete properties.
DELETE WEB_SERVICE_URL/publish/properties/{property_id}
With {property_id} a comma separated list of property ids to delete.
HTTP Status Code | Details |
---|---|
200 | The properties have been deleted |
500 | An error occured on the server side |
400 | Missing the property ids |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"total": 42
}
Platforms
Get configured video platforms.
GET WEB_SERVICE_URL/publish/platforms
HTTP Status Code | Details |
---|---|
200 | Got the platforms |
500 | An error occured on the server side |
401 | Authentication to the web service failed |
403 | Authorization forbidden for this end point |
{
"platforms": [
"vimeo",
"youtube",
"local",
"tls",
"wowza"
]
}