Item resource [VC 21.3.1 GEN]

Manage items.

Managing items

List 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:	See Retrieving item information
Query Parameters:	result (string) – list (default) - Return a list of items. library - Create a library with the matching items. q (string) – XML/JSON, ItemSearchDocument. Only with GET. library (string) – Restricts search to within library, Identifiers. Default is *, all items. first (integer) – From the resulting list of items, start return list from specified offset. Default is 1, start return list from beginning. cursor (string) – New in version 4.16. * - The initial cursor. string-from-search - Cursor string returned from the search results. If set, the cursorMark / search after features from Solr/Elasticsearch would be used to improve the deep paging performance during a search. When cursor is used, The value of first will be ignored. Changed in version 5.5. Starting in 5.5, cursor is returned for the end of the result instead of null to enable tailing search. number (integer) – The number of entities to fetch. Default is 100. count (boolean) – true (default) - Return hits in result. false - Do not return hits in result, in order to produce results faster. libraryId (string) – If set, the library identified by this id will be used instead of creating a new library. autoRefresh (boolean) – When creating a library, make it self-refresh. Default is false. updateMode (string) – When creating a library, use this update mode. Default is MERGE. updateFrequency (string) – When creating a library, use this update frequency. Defaults to no periodic updates. p (string) – Comma-separated list of paths specifying the content to include. Overrides the content and filter parameters. content (string) – Comma-separated list of the types of content to retrieve. Valid values are metadata, uri, shape, poster, thumbnail, access, merged-access, external. interval (string) – 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 as interval=generic,-INF-+INF result - Can be used when retrieving metadata from a search result. Will return time spans that overlap with the search result. (New in 5.5.) field (string) – 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 (string) – Comma-separated list. group-name - Return specified group. group-name + - Return specified group and subgroups. 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 (string) – 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. sampleRate (string) – 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 (string) – 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. include (string) – A list of keys. Includes additional field specific data. Additionally, if set to type the type definition of the field will be retrieved. includeValues (boolean) – Return the value enumeration for each metadata field. conflict (string) – yes (default) - Include all metadata conflicts, unresolved. no - Return conflicts resolved according to field rules. terse (string) – yes - Return metadata in terse format. no (default) - Return metadata in verbose format. defaultValue (boolean) – true - For unset fields, return default values. false (default) - Do not return default values. includeTransientMetadata (boolean) – true (default) - Include transient metadata. false - Do not include transient metadata in response. revision (string) – Specifying which metadata revision to display. Only used if requesting a single item or collection. mergedType (string) – The type of operation to check for. mergedPermission (string) – The lowest required permission level. mergedExtradata (string) – Any possible extra data. uriType (string) – Comma-separated list of format types (container format) to return. scheme (string) – URI scheme to return. storageType (string) – Only return URIs for files from storages of this type. methodType (string) – Access method. 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 (string) – Metadata used with storage method. tag (string) – A URI parameter: Comma-separated list of shape tags to return. version (string) – Specifying which essence version to return for shapes. If special value all, display all versions. If special value latest (default), display latest version of shapes. closedFiles (boolean) – A URI parameter: true (default) - Return only URIs that point to closed files. false - Return all URIs. storage (string[]) – List of storage ids. Return only files from specific storages. Can be specified multiple times. storageGroup (string) – Storage group id. Return only files from storages specified in the storage group. starttc (boolean) – true - Interval is given relative to start timecode of item. false (default) - Interval is 0-based. url (boolean) – true - Return list of URLs. false (default) - Return list of ids. noauth-url (boolean) – true Return URIs that do not need authentication. false (default) Return normal URIs baseURI (string) – Which base URI to use for the thumbnail URLs. save (boolean) – true - Returns a 303 See Other, with a Location header containing an URI to fetch the search result false (default) - Returns a regular search result
Produces:	application/xml, application/json – ItemListDocument text/plain – CRLF-delimited list of ids or URLs
Role:	_item_search
Role:	_metadata_read (content=metadata)
Role:	_item_uri (content=uri)
Role:	_thumbnail_read (content=poster and content=thumbnail)
Role:	_access_control_read (content=access and content=merged-access)
Role:	_item_id_read (content=external)

Additional content can be retrieved by using the syntax specified in Retrieving item information.

Retrieve an item

GET /item/(item-id)

Returns information about a single item.

Query Parameters:	p (string) – Comma-separated list of paths specifying the content to include. Overrides the content and filter parameters. content (string) – Comma-separated list of the types of content to retrieve. Valid values are metadata, uri, shape, poster, thumbnail, access, merged-access, external. interval (string) – 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 as interval=generic,-INF-+INF result - Can be used when retrieving metadata from a search result. Will return time spans that overlap with the search result. (New in 5.5.) field (string) – 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 (string) – Comma-separated list. group-name - Return specified group. group-name + - Return specified group and subgroups. 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 (string) – 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. sampleRate (string) – 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 (string) – 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. include (string) – A list of keys. Includes additional field specific data. Additionally, if set to type the type definition of the field will be retrieved. includeValues (boolean) – Return the value enumeration for each metadata field. conflict (string) – yes (default) - Include all metadata conflicts, unresolved. no - Return conflicts resolved according to field rules. terse (string) – yes - Return metadata in terse format. no (default) - Return metadata in verbose format. defaultValue (boolean) – true - For unset fields, return default values. false (default) - Do not return default values. includeTransientMetadata (boolean) – true (default) - Include transient metadata. false - Do not include transient metadata in response. revision (string) – Specifying which metadata revision to display. Only used if requesting a single item or collection. mergedType (string) – The type of operation to check for. mergedPermission (string) – The lowest required permission level. mergedExtradata (string) – Any possible extra data. uriType (string) – Comma-separated list of format types (container format) to return. scheme (string) – URI scheme to return. storageType (string) – Only return URIs for files from storages of this type. methodType (string) – Access method. 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 (string) – Metadata used with storage method. tag (string) – A URI parameter: Comma-separated list of shape tags to return. version (string) – Specifying which essence version to return for shapes. If special value all, display all versions. If special value latest (default), display latest version of shapes. closedFiles (boolean) – A URI parameter: true (default) - Return only URIs that point to closed files. false - Return all URIs. storage (string[]) – List of storage ids. Return only files from specific storages. Can be specified multiple times. storageGroup (string) – Storage group id. Return only files from storages specified in the storage group. starttc (boolean) – true - Interval is given relative to start timecode of item. false (default) - Interval is 0-based. noauth-url (boolean) – true Return URIs that do not need authentication. false (default) Return normal URIs baseURI (string) – Which base URI to use for the thumbnail URLs.
Produces:	application/xml, application/json – ItemDocument
Role:	_metadata_read (content=metadata)
Role:	_item_uri (content=uri)
Role:	_thumbnail_read (content=poster and content=thumbnail)
Role:	_access_control_read (content=access and content=merged-access)
Role:	_item_id_read (content=external)

Additional content can be retrieved by using the syntax specified in Retrieving item information.

Delete an item

Deleting an item means removing the item’s id, its metadata, shapes, and physical files.

DELETE /item/(item-id)

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.

If any of keepShapeTagMedia or keepShapeTagStorage contains a value *, then no files will be removed.

Changed in version 5.0: New _item_write role required.

Query Parameters:	keepShapeTagMedia (string) – Comma-separated list of shape tags whose files will not be deleted. keepShapeTagStorage (string) – Comma-separated list of storage ids whose files will not be deleted.
Role:	_item_wite

Delete multiple items

Deleting an item means removing the item’s id, its metadata, shapes, and physical files.

DELETE /item

Marks multiple items as being deleted, meaning they will not be returned in search results.

Changed in version 5.0: New _item_write role required.

Query Parameters:	id (string) – Comma-separated list of item ids or external ids. Must not be empty. keepShapeTagMedia (string) – Comma-separated list of shape tags whose files will not be deleted. keepShapeTagStorage (string) – Comma-separated list of storage ids whose files will not be deleted.
Role:	_item_write

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:	See Retrieving item information
Query Parameters:	result (string) – list (default) - Return a list of items. library - Create a library with the matching items. q (string) – XML/JSON, ItemSearchDocument. Only with GET. library (string) – Restricts search to within library, Identifiers. Default is *, all items. first (integer) – From the resulting list of items, start return list from specified offset. Default is 1, start return list from beginning. cursor (string) – New in version 4.16. * - The initial cursor. string-from-search - Cursor string returned from the search results. If set, the cursorMark / search after features from Solr/Elasticsearch would be used to improve the deep paging performance during a search. When cursor is used, The value of first will be ignored. Changed in version 5.5. Starting in 5.5, cursor is returned for the end of the result instead of null to enable tailing search. number (integer) – The number of entities to fetch. Default is 100. count (boolean) – true (default) - Return hits in result. false - Do not return hits in result, in order to produce results faster. libraryId (string) – If set, the library identified by this id will be used instead of creating a new library. autoRefresh (boolean) – When creating a library, make it self-refresh. Default is false. updateMode (string) – When creating a library, use this update mode. Default is MERGE. updateFrequency (string) – When creating a library, use this update frequency. Defaults to no periodic updates. p (string) – Comma-separated list of paths specifying the content to include. Overrides the content and filter parameters. content (string) – Comma-separated list of the types of content to retrieve. Valid values are metadata, uri, shape, poster, thumbnail, access, merged-access, external. interval (string) – 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 as interval=generic,-INF-+INF result - Can be used when retrieving metadata from a search result. Will return time spans that overlap with the search result. (New in 5.5.) field (string) – 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 (string) – Comma-separated list. group-name - Return specified group. group-name + - Return specified group and subgroups. 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 (string) – 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. sampleRate (string) – 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 (string) – 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. include (string) – A list of keys. Includes additional field specific data. Additionally, if set to type the type definition of the field will be retrieved. includeValues (boolean) – Return the value enumeration for each metadata field. conflict (string) – yes (default) - Include all metadata conflicts, unresolved. no - Return conflicts resolved according to field rules. terse (string) – yes - Return metadata in terse format. no (default) - Return metadata in verbose format. defaultValue (boolean) – true - For unset fields, return default values. false (default) - Do not return default values. includeTransientMetadata (boolean) – true (default) - Include transient metadata. false - Do not include transient metadata in response. revision (string) – Specifying which metadata revision to display. Only used if requesting a single item or collection. mergedType (string) – The type of operation to check for. mergedPermission (string) – The lowest required permission level. mergedExtradata (string) – Any possible extra data. uriType (string) – Comma-separated list of format types (container format) to return. scheme (string) – URI scheme to return. storageType (string) – Only return URIs for files from storages of this type. methodType (string) – Access method. 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 (string) – Metadata used with storage method. tag (string) – A URI parameter: Comma-separated list of shape tags to return. version (string) – Specifying which essence version to return for shapes. If special value all, display all versions. If special value latest (default), display latest version of shapes. closedFiles (boolean) – A URI parameter: true (default) - Return only URIs that point to closed files. false - Return all URIs. storage (string[]) – List of storage ids. Return only files from specific storages. Can be specified multiple times. storageGroup (string) – Storage group id. Return only files from storages specified in the storage group. starttc (boolean) – true - Interval is given relative to start timecode of item. false (default) - Interval is 0-based. url (boolean) – true - Return list of URLs. false (default) - Return list of ids. noauth-url (boolean) – true Return URIs that do not need authentication. false (default) Return normal URIs baseURI (string) – Which base URI to use for the thumbnail URLs. save (boolean) – true - Returns a 303 See Other, with a Location header containing an URI to fetch the search result false (default) - Returns a regular search result
Produces:	application/xml, application/json – ItemListDocument text/plain – CRLF-delimited list of ids or URLs
Accepts:	application/xml, application/json – ItemSearchDocument
Role:	_item_search
Role:	_metadata_read (content=metadata)
Role:	_item_uri (content=uri)
Role:	_thumbnail_read (content=poster and content=thumbnail)
Role:	_access_control_read (content=access and content=merged-access)
Role:	_item_id_read (content=external)

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.

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 (string) – An ISO 8601 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 (string) – 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

Create 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 (string) – Required. The URI to output the CSV file to. username (string) – Filter items according to the access of the specified user. groupname (string) – Filter items according to the access of the specified group. field (string) – Comma-separated list of metadata fields to include in the result. Default is title outputFormat (string) – Specifies the output format. One of xml (default) and csv. data (string) – Specifies any additional data that should be included with the metadata fields. p (string) – Comma-separated list of paths specifying the content to include. Overrides the field and data parameters. Only supported for XML output. notification (string) – The placeholder job notification to use for this job. notificationData (string) – Any additional data to include for notifications on this job. priority (string) – The priority to assign to the job. Default is MEDIUM . jobmetadata (string[]) – Additional information for the job task.
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

Retrieves the ids of all collections that includes the item, and that the calling user has read access to.

Produces:

application/xml, application/json – URIListDocument containing the collection ids text/plain – CRLF-delimited list of ids

Example

GET /item/VX-94/collections

<URIListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <uri>VX-23</uri>
  <uri>VX-64</uri>
</URIListDocument>

Parent Libraries

List libraries that contain an item

New in version 4.16.1.

GET /item/(item-id)/library

Retrieves the ids of all libraries that includes the item, and that the calling user has read access to.

This endpoint will not return any transient libraries.

Produces:

application/xml, application/json – URIListDocument containing the library ids text/plain – CRLF-delimited list of ids