Items¶
Managing items¶
Retrieve a list of all items¶
-
GET
/item
¶ Returns a list of all items. This request is the same as performing an empty search.
Note that searching can also be performed by using the HTTP method PUT using the same syntax, except for the parameter
q
is omitted and the ItemSearchDocument is sent in the body of the request.Content Parameters: Query Parameters: - result –
list
(default) - Return a list of items.library
- Create a library with the matching items.
- q – XML/JSON, ItemSearchDocument. Only with GET.
- count –
true
(default) - Return hits in result.false
- Do not return hits in result, in order to produce results faster.
- p –
Comma separated list of paths specifying the content to include. Overrides the content and filter parameters. See Content paths.
New in version 4.5.
- content – Comma-separated list of the types of content to retrieve,
possible values are
metadata
,uri
,shape
,poster
,thumbnail
,access
,merged-access
,external
. - interval –
Comma-separated list
- time-span - Filter out metadata, return only metadata for specified time span.
generic
- Return all non-timed metadata.all
(default) - Return all metadata, same asinterval=generic,-INF-+INF
- field –
Comma-separated list.
- field-name - Return specified field.
- field-name ”:” new-name - Return specified field, renamed to a new name in return value.
- “-” field-name - Exclude specified field.
- (default) - Return all fields.
- group –
Comma-separated list.
- group-name - Return specified group.
- group-name
+
- Return specified group and subgroups.New in version 4.1.
- group-name
:
new-name - Return specified group, renamed to a new name in return value. -
group-name - Exclude specified group.- (default) - Return all groups.
- language –
Comma separated list.
- language-tag -
Return metadata for specific language, e.g.
en_US
. Wildcards may be used, e.g.*_CA
for both Canadian French and Canadian English. none
- Return all metadata without language specification.all
(default) - Return all metadata, with or without language specification.
- language-tag -
Return metadata for specific language, e.g.
- sampleRate – Convert all outgoing time instants to specified rate. NB! Time codes which cannot be expressed in an integer number of samples will be returned as a decimal number, with risk of losing precision.
- track –
Comma separated list.
- track-type track-number -
Return metadata for specified track. Example of track is
A2
. - track-type t1
-
t2 - Return metadata for specified track interval, e.g.A2-4
. - track-type
*
- Return metadata for all tracks of specified type, e.g.A*
. generic
- Return all non-tracked metadata.all
(default) - All metadata, with or without track specification, are returned.
- track-type track-number -
Return metadata for specified track. Example of track is
- include – A list of keys. Includes additional field specific data.
See Field metadata. Additionally, if set to
type
the type definition of the field will be retrieved. - includeValues – Return the value enumeration for each metadata field.
- conflict –
yes
(default) - Include all metadata conflicts, unresolved.no
- Return conflicts resolved according to field rules.
- terse –
yes
- Return metadata in terse format (see Retrieve terse metadata schema)no
(default) - Return metadata in verbose format
- defaultValue –
true
- For unset fields, return default values. See Default values.false
(default) - Do not return default values.
- includeTransientMetadata –
true
(default) - Include transient metadata, see Transient metadata.false
- Do not include transient metadata in response.
- revision – Optional revision, specifying which metadata to display. Only used if requesting a single item or collection.
- mergedType – The type of operation to check for.
- mergedPermission – The lowest required permission level.
- mergedExtradata – Any possible extradata.
- uriType – Optional comma-separated list of format types (container format) to return.
- scheme – URI scheme to return.
- storageType – Only return URIs for files from storages of this type. See Storages.
- methodType –
Optional type of access method. See Storages.
AUTO
- Gives an APInoauth URI to the media. Access to file is tunneled through Vidispine.AZURE_SAS
- If the storage schema is azure:// you can get direct access to the media. The resulting URI will not tunnel through Vidispine but rather point directly to the media location at the azure storage.
- methodMetadata – Optional metadata used with storage method. See Storages.
- tag – A URI parameter, see Get item URI.
- version – Optional integer, specifying which essence version to return for shapes.
If special value
all
, display all versions. If special valuelatest
(default), display latest version of shapes. - closedFiles – A URI parameter, see Get item URI.
- url –
true
- Return list of URLs.false
(default) - Return list of ids.
- noauth-url –
true
Return URIs that do not need authentication.false
(default) Return normal URIs
- baseURI – Which base URI to use for the thumbnail URLs.
- save –
true
- Returns a303 See Other
, with aLocation
header containing an URI to fetch the search resultfalse
(default) - Returns a regular search result
New in version 4.7.
Matrix Parameters: - library – Restricts search to within library, Identifiers. Default is
*
, all items. - first – Integer, from resulting list of items, start return list from specified offset.
Default is
1
, start return list from beginning. - number – Integer, set a limit on maximum number of hits.
Default
100
. - libraryId – If set, the library identified by this id will be used instead of creating a new library.
- autoRefresh – See Self-refreshing libraries. Defaults to
false
. - updateMode – See Self-refreshing libraries. Defaults to
MERGE
. - updateFrequency – See Self-refreshing libraries. Defaults to no periodic updates.
- starttc –
true
- Interval is given relative to start timecode of item.false
(default) - Interval is 0-based.
Produces: - application/xml, application/json – ItemListDocument
- text/plain – CRLF-delimited list of ids or URLs
Role: _item_search
- result –
Tip
Additional content can be retrieved by using the syntax specified in Retrieving item information.
Get information about a single item¶
-
GET
/item/
(item-id)¶ Returns information about a single item.
Query Parameters: - p –
Comma separated list of paths specifying the content to include. Overrides the content and filter parameters. See Content paths.
New in version 4.5.
- content – Comma-separated list of the types of content to retrieve,
possible values are
metadata
,uri
,shape
,poster
,thumbnail
,access
,merged-access
,external
. - interval –
Comma-separated list
- time-span - Filter out metadata, return only metadata for specified time span.
generic
- Return all non-timed metadata.all
(default) - Return all metadata, same asinterval=generic,-INF-+INF
- field –
Comma-separated list.
- field-name - Return specified field.
- field-name ”:” new-name - Return specified field, renamed to a new name in return value.
- “-” field-name - Exclude specified field.
- (default) - Return all fields.
- group –
Comma-separated list.
- group-name - Return specified group.
- group-name
+
- Return specified group and subgroups.New in version 4.1.
- group-name
:
new-name - Return specified group, renamed to a new name in return value. -
group-name - Exclude specified group.- (default) - Return all groups.
- language –
Comma separated list.
- language-tag -
Return metadata for specific language, e.g.
en_US
. Wildcards may be used, e.g.*_CA
for both Canadian French and Canadian English. none
- Return all metadata without language specification.all
(default) - Return all metadata, with or without language specification.
- language-tag -
Return metadata for specific language, e.g.
- sampleRate – Convert all outgoing time instants to specified rate. NB! Time codes which cannot be expressed in an integer number of samples will be returned as a decimal number, with risk of losing precision.
- track –
Comma separated list.
- track-type track-number -
Return metadata for specified track. Example of track is
A2
. - track-type t1
-
t2 - Return metadata for specified track interval, e.g.A2-4
. - track-type
*
- Return metadata for all tracks of specified type, e.g.A*
. generic
- Return all non-tracked metadata.all
(default) - All metadata, with or without track specification, are returned.
- track-type track-number -
Return metadata for specified track. Example of track is
- include – A list of keys. Includes additional field specific data.
See Field metadata. Additionally, if set to
type
the type definition of the field will be retrieved. - includeValues – Return the value enumeration for each metadata field.
- conflict –
yes
(default) - Include all metadata conflicts, unresolved.no
- Return conflicts resolved according to field rules.
- terse –
yes
- Return metadata in terse format (see Retrieve terse metadata schema)no
(default) - Return metadata in verbose format
- defaultValue –
true
- For unset fields, return default values. See Default values.false
(default) - Do not return default values.
- includeTransientMetadata –
true
(default) - Include transient metadata, see Transient metadata.false
- Do not include transient metadata in response.
- revision – Optional revision, specifying which metadata to display. Only used if requesting a single item or collection.
- mergedType – The type of operation to check for.
- mergedPermission – The lowest required permission level.
- mergedExtradata – Any possible extradata.
- uriType – Optional comma-separated list of format types (container format) to return.
- scheme – URI scheme to return.
- storageType – Only return URIs for files from storages of this type. See Storages.
- methodType –
Optional type of access method. See Storages.
AUTO
- Gives an APInoauth URI to the media. Access to file is tunneled through Vidispine.AZURE_SAS
- If the storage schema is azure:// you can get direct access to the media. The resulting URI will not tunnel through Vidispine but rather point directly to the media location at the azure storage.
- methodMetadata – Optional metadata used with storage method. See Storages.
- tag – A URI parameter, see Get item URI.
- version – Optional integer, specifying which essence version to return for shapes.
If special value
all
, display all versions. If special valuelatest
(default), display latest version of shapes. - closedFiles – A URI parameter, see Get item URI.
- noauth-url –
true
Return URIs that do not need authentication.false
(default) Return normal URIs
- baseURI – Which base URI to use for the thumbnail URLs.
Matrix Parameters: - starttc –
true
- Interval is given relative to start timecode of item.false
(default) - Interval is 0-based.
Produces: - application/xml, application/json – ItemDocument
- p –
Tip
Additional content can be retrieved by using the syntax specified in Retrieving item information.
Delete a single item¶
Deleting an item means removing the item’s id, its metadata, shapes, and physical files.
-
DELETE
/item/
(item-id)¶ Query Parameters: - keepShapeTagMedia – Optional comma-separated list of shape tags whose files will not be deleted.
- keepShapeTagStorage – Optional comma-separated list of storage ids whose files will not be deleted.
Semantics¶
Marks the item as being deleted, meaning it will not be returned in search
results. The actual removement from the database is done approximately once
every minute. Also, all files associated with the item is marked as
TO_BE_DELETED
, meaning they will be deleted by the storage supervisor, but
not sooner than all jobs involving the actual file has finished.
By specifying keepShapeTagMedia
and/or keepShapeTagStorage
,
the files associated with the item is not deleted, but simply unassociated
with the item.
If only keepShapeTagMedia
is given, all files belonging to shapes
of the item with any of the given shape tags are preserved.
If only keepShapeTagStorage
is given, all files belonging to the
item residing on the given storages are preserved. If both
keepShapeTagMedia
and keepShapeTagStorage
is given, all files which
both belongs to the specified shapes and storages are preserved.
New in version 4.3.2.
If any of keepShapeTagMedia
or keepShapeTagStorage
contains a value *
,
then no files will be removed.
Delete multiple items¶
Deleting an item means removing the item’s id, its metadata, shapes, and physical files.
New in version 4.8.
-
DELETE
/item
¶ Query Parameters: - id – Comma-separated list of item ids or external ids. Must not be empty.
- keepShapeTagMedia – Optional comma-separated list of shape tags whose files will not be deleted.
- keepShapeTagStorage – Optional comma-separated list of storage ids whose files will not be deleted.
Search items¶
-
PUT
/item
¶ Performs an item search. If the result query parameter is set to library a new library is created, which can be used to further refine the search, using the library parameter.
Content Parameters: Query Parameters: - result –
list
(default) - Return a list of items.library
- Create a library with the matching items.
- q – XML/JSON, ItemSearchDocument. Only with GET.
- count –
true
(default) - Return hits in result.false
- Do not return hits in result, in order to produce results faster.
- p –
Comma separated list of paths specifying the content to include. Overrides the content and filter parameters. See Content paths.
New in version 4.5.
- content – Comma-separated list of the types of content to retrieve,
possible values are
metadata
,uri
,shape
,poster
,thumbnail
,access
,merged-access
,external
. - interval –
Comma-separated list
- time-span - Filter out metadata, return only metadata for specified time span.
generic
- Return all non-timed metadata.all
(default) - Return all metadata, same asinterval=generic,-INF-+INF
- field –
Comma-separated list.
- field-name - Return specified field.
- field-name ”:” new-name - Return specified field, renamed to a new name in return value.
- “-” field-name - Exclude specified field.
- (default) - Return all fields.
- group –
Comma-separated list.
- group-name - Return specified group.
- group-name
+
- Return specified group and subgroups.New in version 4.1.
- group-name
:
new-name - Return specified group, renamed to a new name in return value. -
group-name - Exclude specified group.- (default) - Return all groups.
- language –
Comma separated list.
- language-tag -
Return metadata for specific language, e.g.
en_US
. Wildcards may be used, e.g.*_CA
for both Canadian French and Canadian English. none
- Return all metadata without language specification.all
(default) - Return all metadata, with or without language specification.
- language-tag -
Return metadata for specific language, e.g.
- sampleRate – Convert all outgoing time instants to specified rate. NB! Time codes which cannot be expressed in an integer number of samples will be returned as a decimal number, with risk of losing precision.
- track –
Comma separated list.
- track-type track-number -
Return metadata for specified track. Example of track is
A2
. - track-type t1
-
t2 - Return metadata for specified track interval, e.g.A2-4
. - track-type
*
- Return metadata for all tracks of specified type, e.g.A*
. generic
- Return all non-tracked metadata.all
(default) - All metadata, with or without track specification, are returned.
- track-type track-number -
Return metadata for specified track. Example of track is
- include – A list of keys. Includes additional field specific data.
See Field metadata. Additionally, if set to
type
the type definition of the field will be retrieved. - includeValues – Return the value enumeration for each metadata field.
- conflict –
yes
(default) - Include all metadata conflicts, unresolved.no
- Return conflicts resolved according to field rules.
- terse –
yes
- Return metadata in terse format (see Retrieve terse metadata schema)no
(default) - Return metadata in verbose format
- defaultValue –
true
- For unset fields, return default values. See Default values.false
(default) - Do not return default values.
- includeTransientMetadata –
true
(default) - Include transient metadata, see Transient metadata.false
- Do not include transient metadata in response.
- revision – Optional revision, specifying which metadata to display. Only used if requesting a single item or collection.
- mergedType – The type of operation to check for.
- mergedPermission – The lowest required permission level.
- mergedExtradata – Any possible extradata.
- uriType – Optional comma-separated list of format types (container format) to return.
- scheme – URI scheme to return.
- storageType – Only return URIs for files from storages of this type. See Storages.
- methodType –
Optional type of access method. See Storages.
AUTO
- Gives an APInoauth URI to the media. Access to file is tunneled through Vidispine.AZURE_SAS
- If the storage schema is azure:// you can get direct access to the media. The resulting URI will not tunnel through Vidispine but rather point directly to the media location at the azure storage.
- methodMetadata – Optional metadata used with storage method. See Storages.
- tag – A URI parameter, see Get item URI.
- version – Optional integer, specifying which essence version to return for shapes.
If special value
all
, display all versions. If special valuelatest
(default), display latest version of shapes. - closedFiles – A URI parameter, see Get item URI.
- url –
true
- Return list of URLs.false
(default) - Return list of ids.
- noauth-url –
true
Return URIs that do not need authentication.false
(default) Return normal URIs
- baseURI – Which base URI to use for the thumbnail URLs.
- save –
true
- Returns a303 See Other
, with aLocation
header containing an URI to fetch the search resultfalse
(default) - Returns a regular search result
New in version 4.7.
Matrix Parameters: - library – Restricts search to within library, Identifiers. Default is
*
, all items. - first – Integer, from resulting list of items, start return list from specified offset.
Default is
1
, start return list from beginning. - number – Integer, set a limit on maximum number of hits.
Default
100
. - libraryId – If set, the library identified by this id will be used instead of creating a new library.
- autoRefresh – See Self-refreshing libraries. Defaults to
false
. - updateMode – See Self-refreshing libraries. Defaults to
MERGE
. - updateFrequency – See Self-refreshing libraries. Defaults to no periodic updates.
- starttc –
true
- Interval is given relative to start timecode of item.false
(default) - Interval is 0-based.
Produces: - application/xml, application/json – ItemListDocument
- text/plain – CRLF-delimited list of ids or URLs
Accepts: - application/xml, application/json – ItemSearchDocument
Role: _item_search
- result –
Tip
There is a limit on how many items that can be returned for each call to this method. To get all items, iterate the calls, or even better in a batch scenario, start a job using Listing items in batch to get all items at once.
Tip
Additional content can be retrieved by using the syntax specified in Retrieving item information.
Example¶
GET /item?result=library
Content-Type: application/xml
<ItemSearchDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<field>
<name>product_category</name>
<value>tv</value>
</field>
</ItemSearchDocument>
<ItemListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<library>VX*1233</library>
<item>VY-1233</item>
<item>VY-1234</item>
<item>VX-7888</item>
</ItemListDocument>
PUT /item;library=VX*1233
Content-Type: application/xml
<ItemSearchDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<field>
<name>created</name>
<range>
<value>2014-05-30T00:00:00+0200</value>
<value>2014-06-03T07:30:00+0200</value>
</range>
</field>
</ItemSearchDocument>
<ItemListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<library>VX*1234</library>
<item>VY-1233</item>
<item>VX-7888</item>
</ItemListDocument>
Search history¶
Retrieve search history¶
-
GET
/item/history
¶ Retrieves a list of searches made by a particular user, including “item search” and “Item and collection search”. The results are ordered according to timestamp, with the latest searches being first. Duplicate queries will not be retrieved.
Query Parameters: - start – Optional ISO8601 date. If set, only searches made after this date will be retrieved.
- maxResults – Integer, the maximum number of searches that will be retrieved. The value must be between 1 and 50, default is 10.
- username – The name of the user that has performed the searched. If not specified, the user performing the request will be selected.
Produces: - application/xml, application/json – SearchHistoryDocument.
Role: _item_search
Re-index item¶
-
PUT
/item/
(item-id)/re-index
¶ Queues a single item for re-index.
Produces: - text/plain –
See Re-indexing metadata if you wish to reindex all items in the system.
Listing items in batch¶
Creating an item list job¶
-
POST
/item/list
¶ Starts a new job that goes through all the items available to the user/group and outputs a file to the supplied URI.
If no user and no group is supplied, all items will be retrieved. The output format depends on the specified parameter, if set to XML an ItemListDocument will be produced. Furthermore if an XSLT is given the ItemListDocument will be transformed.
Query Parameters: - destinationUri – The URI to output the CSV file to.
- username – Filter items according to the access of the specified user.
- groupname – Filter items according to the access of the specified group.
- field – A comma-separated list of metadata fields to include in the result.
- outputFormat – Specifies the output format. Valid values are
xml
(default) andcsv
. - data – Specifies any additional data that should be included with the metadata fields.
- p –
Comma-separated list of paths specifying the content to include. Overrides the field and data parameters. Only supported for XML output. See Content paths.
New in version 4.5.
- notification – See Notifications . (Optional)
- notificationData – See Notifications . (Optional)
- priority – The priority to assign to the job. Default is
MEDIUM
. - jobmetadata – Additional information for the job task. See Special job metadata values
Accepts: - application/xslt – An optional XSLT capable of transforming ItemListDocument.
Produces: - application/xml, application/json – JobDocument.
Role: _administrator
Example¶
POST /item/list?field=title,durationSeconds&username=admin&destinationUri=file:/home/user/output.csv&outputFormat=csv
Content-Type: application/xml
<JobDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<jobId>VX-64</jobId>
<user>admin</user>
<started>2010-11-29T11:12:55.768+01:00</started>
<status>READY</status>
<type>LIST_ITEMS</type>
<priority>MEDIUM</priority>
</JobDocument>
$ cat /home/user/output.csv
"itemId","format","fileSize","downloads","metadataField-title","metadataField-durationSeconds"
"VX-22","mxf","10000000","1","","180.0"
"VX-18","mp3,aac","5876698,4253659","0","","212.242695"
"VX-12","flv","23939202","5","This is ""the"" title.","142.124698"
"VX-8","flv","5684452","3","","12.412487"
Parent collections¶
List collections that contain an item¶
-
GET
/item/
(item-id)/collections
¶ Produces: - application/xml, application/json – URIListDocument containing the collection ID of all collections that includes the item, and that the calling user has read access to.
- text/plain – CRLF-delimited list of ids
Role: _item_read
Example¶
GET /item/VX-94/collections
<URIListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
<uri>VX-23</uri>
<uri>VX-64</uri>
</URIListDocument>