Items

Use the items API command to retreive a list of items or perform actions on a single item.

View action

Permissions

The item-view permission is required to perform this action.

Parameters

The list of items can be filtered based on a number of parameters. The parameters are added, so an item has to fullfill all the requirements to be included in the list.

Parameter Std.Value Description
showfiles 0 If 1, show individual files. If 0, show only items
showdeleted 0 If 1, show both deleted and regular items (and files if showfiles=1)
maxresults 20 The maximum number of results returned
offset 0 Start at this result while outputting (start at 0)
queryorder desc Order the results ‘asc’ending or ‘desc’ending
queryorderby (empty) Field to order by, currently title, date, duration, and views are supported.
fileextension (empty) Only show items if one of their files has this extension (use ‘flv’ not ‘.flv’)
itemid (empty) Only show this ItemId (can be used to fetch item-information when playing a single item; separate multiple ItemIds with commas (,) )
categoryid (empty) Only show items from this category (separate multiple categories with commas (,) )
searchtitle (empty) Only show items with this string in the title
searchdescription (empty) Only show items with this string in the description
searchkeywords (empty) Only show items with this string in the keywords
searchfulltext (empty) Only show items with this string in either title, description or keywords
exactsearch 0 If 1, perform an exact search (meaning “123test” is not found if searching for “23test”)
viewsmin 0 Only show items with at least this number of views
viewsmax infinite Only show items with at most this number of views
datemin YYYY-MM-DD Only show items at or after this date (YYYY-MM-DD HH:MM and YY-MM-DD HH:MM:SS supported as well)
datemax YYYY-MM-DD Only show items at or before this date (YYYY-MM-DD HH:MM and YY-MM-DD HH:MM:SS supported as well)
mdatemin YYYY-MM-DD Only show items changed at or after this date (YYYY-MM-DD HH:MM and YY-MM-DD HH:MM:SS supported as well)
mdatemax YYYY-MM-DD Only show items changed at or before this date (YYYY-MM-DD HH:MM and YY-MM-DD HH:MM:SS supported as well)
itemtypeid (empty) Only show items of this type. 1=audio only, 2=video+audio, 3=video only
showcategories 0 Output the categories this item belongs to. This produces a ‘categories’ key with an array of ‘categoryId’=>’categoryName’ pairs.
showemptyitems 0 Output empty items as well? Empty items are items without any files (and thus cannot be played). This option cannot be combined with showfiles=1, if showfiles=1 is specified, empty items are never displayed.
showarchived 0 Ouput archived items? 0=no, 1=yes, show archived along with current items, 2=only archived
showthumbdetails 0 Show thumbnail/screenshot details (number of screenshots, currently selected screenshot). 0 or 1

Besides these paramaters, the common parameters should be used here. The outputtype parameter is mandatory.

Output in serialized php or JSON

The output can be in Serialized PHP or JSON format. The output is an array, which contains an entry for every requested item. This array looks like ( $ItemId1 => ( item-info1 ), $ItemId2 => ( item-info2 ), ... ).

In the header of the total output structure, an extra field is added: totalresults. This is the total number of results from the query, independant from the used offset and maxresults. This value can be used for easy paginating.

Every item-info array consists of these fields:

  • title = Title of the item
  • author = Author of the item
  • copyright = Copyright notice of this item
  • description = Description of the item
  • keywords = Keywords associated with this item
  • deleted = 0 or 1: If the item is deleted, is 1 in which case undeleting the item may still be possible
  • externalLink = An external link (e.g. where more info can be found or the page this video belongs to)
  • archived = 0 or 1: Is this item archived? Archived means it is no longer publicly available
  • externalId = An Id to identify this item with in an external system
  • externalId2 = Second Id to identify this item with in an external system
  • dateAdded = The date on which the item was added. When recording live-events, this is the date the item was aired. Format is YYYY-MM-DD HH:MM:SS
  • dateModified = The date on which the item or one of its files was last modified.
  • duration = Duration of the item, in seconds
  • accountId = Hashcode of the account this item belongs to
  • views = Number of views this item has so far
  • itemId = The ID of the item (this is the external id, or if not present the streamone id is returned)
  • itemTypeId = The type of the item
  • itemTypeName = Name of the itemType
  • globalUserRights = 0 or 1: Can everybody view this item? If not, API authentication is required to view it. Note that the security profile always applies!
  • videoAspect = Aspect ratio of this video (this is a floating-point number like 1.333333 for 1.333333:1 aspect ratio (in this example 4:3))
  • userId = If not NULL, this is the hashcode of the user this item belongs to. This means only this user can edit this video (or perform other actions on it).
  • securityProfileId = If not NULL, this security profile is applied to this video.
  • isEmpty = (Only when showemptyitems=1) 0 or 1: Is this item empty or not? 1 means empty, meaning the item has no files and cannot be played.
  • isArchived = 0 or 1: Is this item archived or not? If archived, it won’t show up in regular searches.
  • thumbnail = Full URL to the thumbnail of the item
  • thumbCount = Total number of thumbnails for the item (they are numbered 1-thumbCount)
  • thumbSelected = Which thumbnail number is currently selected as the thumbnail for this item
  • streamUrl = Full URL to stream this item
  • categories = Array with ‘categoryId’=>’categoryName’ pairs. Only present when showcategories=1‘.
  • mediaLink = Array with direct links to the media content (possible types/keys are hls and progressive), player or platform will auto-sense quality or use variable bitrate technology

If there are multiple files present, there is an array key files which consists of an array of file-info-arrays. Each of these arrays has these fields:

  • deleted = 0 or 1: If the file is deleted, is 1 in which case undeleting the file may still be possible
  • width = Width of this videofile
  • weight = Height of this videofile
  • fileId = Id of this file (hashcode), can be used for streaming a single file
  • fileSize = Size of the file in bytes
  • audioBitrate = Bitrate of the audio stream (in kbit/sec)
  • videoBitrate = Bitrate of the video stream (in kbit/sec)
  • bitrate = Total bitrate of the videofile (in kbit/sec)
  • framerate = Framerate of the video (in frames/sec)
  • videoAspect = Aspect ratio of the video (1:xxxx)
  • audioSampleRate = Samplerate of the audio (samples/sec)
  • audioSampleBitDepth = Number of bits for the audio samples
  • audioChannels = Number of audio channels
  • profileId = The id of the profile used for encoding
  • profileName = The name of the profile used for encoding
  • mimeType = MIME type of the video
  • videoCodecName = Name of the video codec (like h264)
  • audioCodecName = Name of the audio codec (like aac)
  • streamUrl = Full url to stream this file
  • fileType = Type of this file (1=audio only, 2=video+audio, 3=video only, 4=image, 5=binary file)
  • fileTypeName = Name of the type
  • fileNameHR = Full filename of the original file
  • videoCodecProfileId = The (integer) ID of the VideoCodecProfile
  • videoCodecProfile = Name of the VideoCodecProfile (e.g. Baseline or Main)
  • videoCodecProfileLevel = The level of the profile
  • itemFileFormatId = (Integer) ID of the file format
  • itemFileFormat = Name of the file format (e.g. MPEG-4 or Flash Video)
  • videoIsInterlaced = 0 or 1: is the video interlaced?
  • videoIsVBR = 0 or 1: is VBR used for encoding the video?
  • fileCorruptionDetection = 0 or 1: will file corruption be detected?
  • dateCreated = The date and time at which the file was created
  • origin = The ID of the origin of this file (1=source file, 2=transcoded file, 3=recorded file)
  • originName = The name of the origin (e.g. “Transcoded file”)

Create action

This creates an empty item (that means it has no files in it) with the specified parameters.

Permissions

The item-create permission is required to perform this action.

Parameters

These fields can optionally be specified for the new item (see above for the description):

  • title
  • author
  • copyright
  • description
  • keywords
  • externallink
  • archived (can be 0 or 1)
  • dateaired (format: YYYYMMDDHHMMSS)
  • isglobal (can be 0 or 1)
  • videoaspect
  • userid
  • securityprofileid
  • externalid
  • externalid2

Authentication

Creating a new item is only possible after authenticating.

Output

If the item was created successfully, statuscode 0 is returned. Any other code means something went wrong.

On successfull creation, an array is returned with the ItemId of the newly created item, like this:

( 'itemId' => 'jho78Ytn0' )

Edit action

Permissions

The item-edit permission is required to perform this action.

Parameters

Multiple fields can be edited at the same time. To identify which item to edit, the StreamOne itemId or the externalId can be used. Note that the externalId and externalId2 can only be edited when the StreamOne itemId is given as identifier, if itemId is not present, the externalId or externalId2 is used to identify the item.

These fields can be edited:

  • title
  • author
  • copyright
  • description
  • keywords
  • externallink
  • archived (can be 0 or 1)
  • dateaired (format: YYYYMMDDHHMMSS)
  • isglobal (can be 0 or 1)
  • videoaspect
  • userid
  • securityprofileid (specify none if no security profile should be used)
  • externalid (can also be used to identify the item to edit, see the note above)
  • externalid2 (idem)

Examples

/items/edit/api=2?title=bla&description=abcd&externalid=myid1234 (changes title to bla, description to abcd where externalid=myid1234)

/items/edit/api=2/title=mymovie/author=me/itemid=abH7T4ra1p/externalid=myid123 (changes title to mymovie, author to me, externalid to myid123 where the StreamOne itemId is abH7T4ra1p)

Authentication

Editing is only possible after authenticating.

Output

The output of the edit action can be one of the following statuscodes:

  • 0 If the edit was successfull
  • 2 If the given user is not allowed to edit this item
  • 4 If the given user doesn’t have item-edit-rights
  • 5 If there was a problem with the input (e.g. invalid values)

Besides these codes, the status codes as can be found in the Authentication document can also be returned.

Delete action

This deletes an item and all associated itemfiles.

Permissions

The item-delete permission is required to perform this action.

Parameters

There is only one parameter needed, to determine which item to delete.

This can be done by either the itemid, externalid or externalid2 parameter.

Authentication

Deletion is only possible after authentication.

Output

To check if the delete operation succeded, check the statuscode. Statuscode 0 means the item was successfully deleted. Any other number means something went wrong.

Undelete action

This undeletes an item and all associated itemfiles. It will also undelete associated itemfiles that were individually deleted, but not yet permanently deleted earlier.

Permissions

The item-delete permission is required to perform this action (the same as for the Delete Action).

Parameters

There is only one parameter needed, to determine which item to undelete.

This can be done by either the itemid, externalid or externalid2 parameter.

Authentication

Undeletion is only possible after authentication.

Output

To check if the undelete operation succeded, check the statuscode. Statuscode 0 means the item was successfully undeleted. Any other number means something went wrong.

Merge action

This will merge two items, deleting the original item’s files and replacing them with files from the donor item (even if those files are already deleted). The original item’s files can still be manually undeleted after the merge action. This is not recommended, especially when using multiple/variable bitrate content.

Permissions

The item-merge permission is required to perform this action.

Parameters

There are two parameters needed, the itemid and the donoritemid. External ID parameters are not supported by the Merge Action.

Authentication

Deletion is only possible after authentication.

Output

To check if the delete operation succeded, check the statuscode. Statuscode 0 means the item was successfully merged. Any other number means something went wrong.

AddToCategory action

This command adds an item to a category.

Permissions

The item-categorize permission is required to perform this action. We apologise to UK English people for the nomenclature.

Parameters

There are two parameters needed.

First, the item is to be determined, using either the itemid, externalid or externalid2 parameter. Furthermore, the category is needed, for this the category parameter is used. This should be the hashcode of the category.

Authentication

Adding a category is only possible after authentication.

Output

To check if the operation succeded, check the statuscode. Statuscode 0 means it was successfull, any other statuscode means something went wrong.

There is one extra statuscode besides the default codes as mentioned in Authentication:

  • 10 Item already exists in this category

RemoveFromCategory action

This command removes an item from a category.

Permissions

The item-categorize permission is required to perform this action.

Parameters

There are two parameters needed.

First, the item is to be determined, using either the itemid, externalid or externalid2 parameter. Furthermore, the category is needed, for this the category parameter is used. This should be the hashcode of the category.

Authentication

Removing a category is only possible after authentication.

Output

To check if the operation succeded, check the statuscode. Statuscode 0 means it was successfull, any other statuscode means something went wrong.

There is one extra statuscode besides the default codes as mentioned in Authentication:

  • 11 Item doesn’t belong to this category

CreateUploadToken action

It is possible to upload files using HTTP upload. To do this, an upload token is needed. These upload tokens can be created using this API command.

Permissions

The item-upload permission is required to perform this action. Additionally, the item-screenshot-upload token is required to upload a screenshot (thumbnail) to an existing item (if fileType is 7).

Parameters

The item can be determined. That can be done using either the itemid, externalid or externalid2 parameter. If no item is given, a new item will automatically be created after the upload was completed.

Besides the default authentication parameters, these parameters can be set:

Parameter Description
validityperiod How long is the token is valid, specified in seconds. If not specified, defaults to 3600 seconds (1 hour).
itemid See above
setuser When uploading, tie the item to this user. If not specified, the upload is only tied to the account belonging to the user used to sign the API request with. This value should be the hashcode of the desired user.
fileType Type of this file (1=audio only, 2=video+audio, 3=video only, 4=image, 5=binary file, 6=thumbnail, 7=thumbnail and select this thumbnail)

Authentication

Creating a token is only possible after authenticating.

Output

The output of this action is an array consisting of two items:

  • 'uploadToken' => 'akjdhg0987HAFajfaYlafpqZmv878KApnbv709751Zui7Bjt5Gapl'
  • 'uploadURL' => 'http://upload.streamone.nl/upload'

Always check the statuscode to see if the command succeded. If it is, the statuscode is 0.

The file-upload can be HTTP POSTed to the given URL (don’t forget enctype="multipart/form-data"). These fields should/can be in the form:

  • uploadtoken = The upload token (case-sensitive) as received from the API, required
  • returnurl = The URL where the user will be redirected after the upload. ?error=(some error code) is appended when something went wrong, required
  • uploadfile = (type=file) The file to upload, required
  • title = (when creating a new item) Title of the item, optional
  • author = (when creating a new item) Author of the item, optional
  • description = (when creating a new item) Description of the item, optional

ListScreenshots action

Retrieve a list of all screenshots for a certain item.

Permissions

The item-screenshot-list permission is required to perform this action.

Parameters

The item needs to be determined. That can be done using either the itemid, externalid or externalid2 parameter.

Authentication

Retrieving all screenshots is only possible after authentication.

Output

The output is an array: ($screenshotId1 => $screenshotInfo1, $screenshotId2 => $screenshotInfo2) , with every screenshotInfo array consisting of:

  • thumbURL Full URL of the 160x120 version of the screenshot.
  • screenshotURL Full URL of the original-size screenshot.
  • isDefault 0 or 1: Is this de default screenshot for this item? Only one screenshot can have value this set to 1.

SelectScreenshot action

Select a new screenshot as default for this item.

Permissions

The item-screenshot-select permission is required to perform this action.

Parameters

First, the item needs to be determined. That can be done using either the itemid, externalid or externalid2 parameter. Furthermore, the selected screenshot is required, this is done with the screenshotid parameter and this should be the (integer) id of the new default screenshot.

Authentication

Setting a new default screenshot is only possible after authentication.

Output

If the statuscode is 0, the request succeded. Any other code means something went wrong.

When statuscode 13 is returned, the selected thumbnail is not found.

DeleteItemFile action

This action deletes one or all ItemFiles from the item. This is usefull when a transcode job somehow went wrong and the wrongly encoded files have to be deleted.

Permissions

The itemfile-delete permission is required to perform this action.

Parameters

The item needs to be determined. That can be done using either the itemid, externalid or externalid2 parameter. Furthermore the ItemFile is needed, this is done using the itemfileid parameter, which should be set to the hashcode of the itemfile to delete. Instead of a hashcode, all can be specified to delete all itemfiles belonging to this item.

Finally, to be sure the files can be deleted, specify iamsure=yes .

If an error has been made, it is (for a short period) possible to undelete a deleted itemfile. To do this, specify undelete=1 . The API will report with statuscode 0 if the undelete succeded.

Authentication

Deleting an ItemFile is only possible after authentication.

Output

If the statuscode is 0, the itemfile was successfully deleted. Any other code means something went wrong.

AddRelatedItem action

Add a related item for this item. Please note that this is a one-way system: if you add Related Item X to Item A, Item A will not be a Related Item for Item X. This allows more control over relationships that are visible to users.

Permissions

The item-edit permission is required to perform this action.

Parameters

Firstly, the item needs to be determined. That can be done using either the itemid, externalid or externalid2 parameter. Secondly, the related item needs to be determined. At this time this is only possible by using the itemid parameter.

Optionally, you can include a sort weight (0-100; 0 is low weight indicating a weak relationship, 100 is a high weight, indicating a strong relationship).

Authentication

Only standard authentication is required.

Output

If the statuscode is 0, the request succeded. Any other code means something went wrong.

ViewRelatedItems action

View the related items for this item.

Permissions

The item-view permission is required to perform this action.

Parameters

Only the item needs to be determined. That can be done using either the itemid, externalid or externalid2 parameter. There are no other parameters.

Authentication

Only standard authentication is required.

Output

If the statuscode is 0, the request succeded. Any other code means something went wrong.

RemoveRelatedItem action

Remove a related item for this item.

Permissions

The item-edit permission is required to perform this action.

Parameters

Firstly, the item needs to be determined. That can be done using either the itemid, externalid or externalid2 parameter. Secondly, the related item needs to be determined. At this time this is only possible by using the itemid parameter.

There is no Relation ID, so the combination needs to be supplied in order to remove the relation.

Authentication

Only standard authentication is required.

Output

If the statuscode is 0, the request succeded. Any other code means something went wrong.