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
searchInPois	Number	No	0	1 to also search in tags / chapters titles and descriptions, 0 to search only on title and description of videos
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, zip 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"
  ]
}