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:
 

See Retrieving item information

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 as interval=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.
  • 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.
  • 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
  • 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 value latest (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 a 303 See Other, with a Location header containing an URI to fetch the search result
    • false (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/jsonItemListDocument
  • text/plain – CRLF-delimited list of ids or URLs
Role:

_item_search

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 as interval=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.
  • 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.
  • 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
  • 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 value latest (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:

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:
 

See Retrieving item information

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 as interval=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.
  • 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.
  • 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
  • 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 value latest (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 a 303 See Other, with a Location header containing an URI to fetch the search result
    • false (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/jsonItemListDocument
  • text/plain – CRLF-delimited list of ids or URLs
Accepts:
Role:

_item_search

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.

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:
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) and csv.
  • 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:
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/jsonURIListDocument 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>