Collections

A collection is an ordered logical set of items, libraries and other collections.

Tip

Access to collections and their item and collection content can be set using access control lists.

Managing collections

Retrieve a list of all collections

GET /collection

Retrieves a list of all known collections.

Matrix Parameters:
 
  • first – Integer, from resulting list of items, start return list from specified offset. Default is 1, start return list from beginning.
  • cursor

    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.

    Only metadata searches in the generic interval supports cursor.

  • number – Integer, the number of entities to fetch. Default 100.
Query Parameters:
 
  • count
    • true (default) - Return hits in result.
    • false - Do not return hits in result, in order to produce results faster.
  • content – Optional comma-separated list of addition content to retrieve. Possible values are: metadata, 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.
  • 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.
  • 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.
  • conflict
    • yes (default) - Include all metadata conflicts, unresolved.
    • no - Return conflicts resolved according to field rules.
  • include – A list of keys. Includes additional field specific data. Additionally, if set to type the type definition of the field will be retrieved.
  • defaultValue
    • true - For unset fields, return default values.
    • false (default) - Do not return default values.
  • includeTransientMetadata
    • true (default) - Include transient metadata.
    • false - Do not include transient metadata in response.
  • includeValues – Return the value enumeration for each metadata field.
  • terse
    • yes - Return metadata in terse format.
    • no (default) - Return metadata in verbose format.
  • 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.
Produces:
Role:

_collection_read

Create a collection

POST /collection

Generates a new collection and returns the id associated with that collection.

Query Parameters:
 
  • name – Optional name of the collection.
  • externalId – An external identifier to assign to the collection.
  • settings – Pre-configured import settings.
Produces:
  • application/xml, application/jsonCollectionDocument
  • text/plain – CRLF-delimited list of ids
Status Codes:
  • 400 – If the external id is already in use.
Role:

_collection_write

POST /collection

Generates a new collection and returns the id associated with that collection.

This resource accepts a collection document that can contain both metadata that should be set for the collection and the entities that it should contain.

New in version 4.8.

Query Parameters:
 
  • name – Optional name of the collection.
  • externalId – An external identifier to assign to the collection.
  • settings – Pre-configured import settings.
Accepts:
Produces:
  • application/xml, application/jsonCollectionDocument
  • text/plain – CRLF-delimited list of ids
Status Codes:
  • 400 – If the external id is already in use.
Role:

_collection_write

Delete a collection

DELETE /collection/(collection-id)

Delete specified collection.

Note that the actual items and libraries that are contained within the collection are not modified.

Status Codes:
  • 200 OK – The collection is deleted.
  • 404 Not found – Could not find the collection.
Role:

_collection_write

Delete multiple collections

New in version 4.8.

DELETE /collection

Delete multiple collections.

Note that the actual items and libraries that are contained within the collection are not modified.

Query Parameters:
 
  • id – Comma-separated list of collection ids or external ids. Must not be empty.
Status Codes:
  • 200 OK – The collections are deleted.
  • 404 Not found – Could not find the collection.
Role:

_collection_write

Example

DELETE /collection?id=VX-32,VX-56

Rename a collection

PUT /collection/(collection-id)/rename

Renames the collection with the Identifiers collection-id.

Query Parameters:
 
  • name – Mandatory, new name of the collection.
Role:

_collection_write

Collection content

Retrieve the contents of a collection

GET /collection/(collection-id)

Return the ids of the objects contained within the collection, that has the id collection-id.

Query Parameters:
 
  • content – Optional comma-separated list of addition content to retrieve. Possible values are: metadata, 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.
  • 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.
  • 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.
  • conflict
    • yes (default) - Include all metadata conflicts, unresolved.
    • no - Return conflicts resolved according to field rules.
  • include – A list of keys. Includes additional field specific data. Additionally, if set to type the type definition of the field will be retrieved.
  • defaultValue
    • true - For unset fields, return default values.
    • false (default) - Do not return default values.
  • includeTransientMetadata
    • true (default) - Include transient metadata.
    • false - Do not include transient metadata in response.
  • includeValues – Return the value enumeration for each metadata field.
  • terse
    • yes - Return metadata in terse format.
    • no (default) - Return metadata in verbose format.
  • 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.
Status Codes:
  • 404 Not found – Could not find the collection.
Produces:
  • application/xml, application/jsonCollectionDocument
  • text/plain – CRLF-delimited list of ids
Role:

_collection_read

Retrieve the items of a collection

GET /collection/(collection-id)/item

Retrieves only the items of the collection.

Changed in version 4.4: Queries on collection items will now return items in creation order by default. See indexCollectionItemOrder on how to revert back to using the insert/custom collection item ordering.

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.

    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. 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.
    • no (default) - Return metadata in verbose format.
  • defaultValue
    • true - For unset fields, return default values.
    • false (default) - Do not return default values.
  • includeTransientMetadata
    • true (default) - Include 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.
  • methodType

    Optional type of 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 – Optional metadata used with storage method.
  • tag – A URI parameter: Optional comma-separated list of shape tags to return.
  • 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:

    • true (default) - Return only URIs that point to closed files.
    • false - Return all URIs.
  • 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.
  • cursor

    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.

    Only metadata searches in the generic interval supports cursor.

  • number – Integer, the number of entities to fetch. Default 100.
  • libraryId – If set, the library identified by this id will be used instead of creating a new library.
  • autoRefresh – When creating a library, make it self-refresh. Defaults to false.
  • updateMode – When creating a library, use this update mode. Defaults to MERGE.
  • updateFrequency – When creating a library, use this update frequency. Defaults to no periodic updates.
  • storage

    Optional list of storage ids. Return only files from specific storages. Can be specified multiple times.

    New in version 4.13.

  • storageGroup

    Optional storage group id. Return only files from storages specified in the storage group.

    New in version 4.13.

  • 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
  • application/xml, application/jsonItemListDocument
  • text/plain – CRLF-delimited list of ids or URLs.
Status Codes:
  • 404 Not found – Could not find the collection.
Role:

_collection_read

Retrieve the ancestors of a collection

GET /collection/(collection-id)/ancestor

Retrieves the ids of all ancestors of the collection.

Produces:
  • application/xml, application/jsonURIListDocument
  • text/plain – CRLF-delimited list of ids
Role:

_collection_read

Search for items within a collection

New in version 4.0.

PUT /collection/(collection-id)/item

Performs a search among the items in the specified collection.

Note

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.

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, use Listing items in batch.

Changed in version 4.4: Queries on collection items will now return items in creation order by default. See indexCollectionItemOrder on how to revert back to using the insert/custom collection item ordering.

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.

    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. 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.
    • no (default) - Return metadata in verbose format.
  • defaultValue
    • true - For unset fields, return default values.
    • false (default) - Do not return default values.
  • includeTransientMetadata
    • true (default) - Include 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.
  • methodType

    Optional type of 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 – Optional metadata used with storage method.
  • tag – A URI parameter: Optional comma-separated list of shape tags to return.
  • 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:

    • true (default) - Return only URIs that point to closed files.
    • false - Return all URIs.
  • 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.
  • cursor

    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.

    Only metadata searches in the generic interval supports cursor.

  • number – Integer, the number of entities to fetch. Default 100.
  • libraryId – If set, the library identified by this id will be used instead of creating a new library.
  • autoRefresh – When creating a library, make it self-refresh. Defaults to false.
  • updateMode – When creating a library, use this update mode. Defaults to MERGE.
  • updateFrequency – When creating a library, use this update frequency. Defaults to no periodic updates.
  • storage

    Optional list of storage ids. Return only files from specific storages. Can be specified multiple times.

    New in version 4.13.

  • storageGroup

    Optional storage group id. Return only files from storages specified in the storage group.

    New in version 4.13.

  • 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:
Status Codes:
Role:

_collection_read

Example

GET /collection/VX-76/item
Accept: application/xml
<ItemListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <item id="VX-45"/>
  <item id="VX-46"/>
  <item id="VX-47"/>
  <item id="VX-62"/>
</ItemListDocument>

Add an item, library or collection to a collection

PUT /collection/(collection-id)/(id)

Adds an item, library or collection with the id id, to the collection with the id collection-id. If id is already present within the collection, this is a no-op, except if the query parameter metadata is used. In that case, metadata is updated for the specified entity.

Query Parameters:
 
  • type
    • collection - The object identified by id is a collection.
    • item (default) - The object identified by id is an item.
    • library - The object identified by id is a library.
  • addItems
    • true - Library items will be added individually. Only has any effect when type=library.
    • false - Library will be added to collection, not specific items.
  • metadata
    • key = value - Set or add metadata field to the relation between the collection and entity. Can be used multiple times to add several fields. The key cannot be empty or start with a minus sign. To delete a field enter the same key with a minus sign at the beginning.

    Note that = is part of the query parameter, and has to be encoded (%3d).

    New in version 4.7.

Status Codes:
  • 200 OK – The collection, item or library was added, or already existed within the collection.
  • 400 Bad request – Cannot add a collection to itself, the type was given an invalid value or a metadata key is not specified.
  • 404 Not found – Could not find the collection, item or library.
Role:

_collection_write

Example

PUT /collection/VX-1000/VX*10?type=library?metadata=addedBy=admin&metadata=dateAdded=Feb 2, 2018
HTTP/1.1 200 OK

Remove an item, library or collection from a collection

DELETE /collection/(collection-id)/(id)

Attempts to remove specific content with the id, id, from a collection with the id collection-id.

Note that the object corresponding to the id is not altered.

Query Parameters:
 
  • type
    • collection - The object identified by id is a collection.
    • item (default) - The object identified by id is an item.
    • library - The object identified by id is a library.
Status Codes:
  • 200 OK – The item/library is removed from the collection.
  • 400 Bad request – The type was given an invalid value.
  • 404 Not found – Could not find the collection or the item/library.
Role:

_collection_write

Update a collection

New in version 4.7.

PUT /collection/(collection-id)

Updates the content of the collection with the id collection-id as specified in the document. It is also possible to change the name of the collection and metadata of the collection-entity relations.

Either all or no entities must have a mode specified. If no entities have a mode specified and the document contains an entity that does not exist in the collection, then the entity will be added.

When no entities have a mode specified the entities will get the same position as they are ordered in the document.

Query Parameters:
 
  • clear
    • true (default) - All entities that are in the collection but not specified in the document will be removed. Only has any effect when no entities have a mode specified.
    • false - All entities in the document will be appended to the collection. If an entity already exist in the collection then the position is determined by the document. Only has any effect when no entities have a mode specified.
Accepts:
Produces:
  • application/xml, application/jsonCollectionDocument containing the collection name and the entities in order.
Status Codes:
  • 200 OK – All operations in the document was successfully completed.
  • 404 Not found – Could not find one of the entities.
  • 400 Invalid input – Invalid type specified, all or none entities have not a mode specified or an entity is specified twice in the document.
Role:

_collection_write

Example: Modify an entire collection

Here is an example where the name of the collection is changed and some entities are added, removed and repositioned. First GET /collection/(collection-id) is used to get the content. The content is then modified and applied with PUT /collection/(collection-id)?clear=true.

GET /collection/VX-1000
<CollectionDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <loc>http://localhost:8080/API/collection/VX-1000/</loc>
  <id>VX-1000</id>
  <name>Old name</name>
  <content>
    <id>VX-1</id>
    <uri>http://localhost:8080/API/item/VX-1</uri>
    <type>item</type>
    <metadata/>
  </content>
  <content>
    <id>VX-2</id>
    <uri>http://localhost:8080/API/item/VX-2</uri>
    <type>item</type>
    <metadata/>
  </content>
  <content>
    <id>VX-3</id>
    <uri>http://localhost:8080/API/item/VX-3</uri>
    <type>item</type>
    <metadata>
      <field>
        <key>AddedBy</key>
        <value>foo</value>
      </field>
    </metadata>
  </content>
  <content>
    <id>VX*20</id>
    <uri>http://localhost:8080/API/library/VX*20</uri>
    <type>library</type>
    <metadata/>
  </content>
  <content>
    <id>VX-100</id>
    <uri>http://localhost:8080/API/collection/VX-100</uri>
    <type>collection</type>
    <metadata>
      <field>
        <key>AddedBy</key>
        <value>Admin</value>
      </field>
    </metadata>
  </content>
  <content>
    <id>VX-200</id>
    <uri>http://localhost:8080/API/collection/VX-200</uri>
    <type>collection</type>
    <metadata/>
  </content>
  <content>
    <id>VX-300</id>
    <uri>http://localhost:8080/API/collection/VX-300</uri>
    <type>collection</type>
    <metadata/>
  </content>
</CollectionDocument>
PUT /collection/VX-1000?clear=true
Content-Type: application/xml

<CollectionDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <loc>http://localhost:8080/API/collection/VX-1000/</loc>
  <id>VX-1000</id>
  <!-- Change the name to "New name" -->
  <name>New name</name>

  <!-- Swap the positions of item VX-1 and item VX-2 -->
  <content>
    <id>VX-2</id>
    <uri>http://localhost:8080/API/item/VX-2</uri>
    <type>item</type>
    <metadata/>
  </content>
  <content>
    <id>VX-1</id>
    <uri>http://localhost:8080/API/item/VX-1</uri>
    <type>item</type>
    <metadata/>
  </content>

  <!-- Change value on the key "AddedBy" to "bar" in the metadata field of item VX-3 -->
  <content>
    <id>VX-3</id>
    <uri>http://localhost:8080/API/item/VX-3</uri>
    <type>item</type>
    <metadata>
      <field>
        <key>AddedBy</key>
        <value>bar</value>
      </field>
    </metadata>
  </content>

  <!-- Add library V*10. If addItems=true then the items in the library
  will be added instead of the library. addItems is by default false
  and only has effect on libraries. -->

  <content addItems="false">
    <id>VX*10</id>
    <uri>http://localhost:8080/API/library/VX*10</uri>
    <type>library</type>
    <metadata/>
  </content>
  <content>
    <id>VX*20</id>
    <uri>http://localhost:8080/API/library/VX*20</uri>
    <type>library</type>
    <metadata/>
  </content>

<!-- Remove the metadata from VX-100 -->
  <content>
    <id>VX-100</id>
    <uri>http://localhost:8080/API/collection/VX-100</uri>
    <type>collection</type>
  </content>

  <content>
    <id>VX-200</id>
    <uri>http://localhost:8080/API/collection/VX-200</uri>
    <type>collection</type>
    <metadata/>
  </content>

  <!-- Collection VX-300 will be removed since clear=true and the
  collection VX-300 is not specified here in the document -->
</CollectionDocument>
<CollectionDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <content>
        <id>VX-2</id>
        <type>item</type>
        <uri>http://localhost:8080/API/item/VX-2</uri>
        <metadata/>
    </content>
    <content>
        <id>VX-1</id>
        <type>item</type>
        <uri>http://localhost:8080/API/item/VX-1</uri>
        <metadata/>
    </content>
    <content>
        <id>VX-3</id>
        <type>item</type>
        <uri>http://localhost:8080/API/item/VX-3</uri>
        <metadata>
          <field>
            <key>AddedBy</key>
            <value>bar</value>
          </field>
        </metadata>
    </content>
    <content>
        <id>VX*10</id>
        <type>library</type>
        <uri>http://localhost:8080/API/library/VX*10</uri>
        <metadata/>
    </content>
    <content>
        <id>VX*20</id>
        <type>library</type>
        <uri>http://localhost:8080/API/library/VX*20</uri>
        <metadata/>
    </content>
    <content>
        <id>VX-100</id>
        <type>collection</type>
        <uri>http://localhost:8080/API/collection/VX-100</uri>
    </content>
    <content>
        <id>VX-200</id>
        <type>collection</type>
        <uri>http://localhost:8080/API/collection/VX-200</uri>
        <metadata/>
    </content>
    <id>VX-1000</id>
    <name>New name</name>
</CollectionDocument>

Example: Specify each change of a collection

To state each change, instead of using a document with all entities, a content mode can be specified to each content. The different modes are “add”, “remove” and “move”. The following example is a continuation of the previous example.

PUT /collection/VX-1000
Content-Type: application/xml

<CollectionDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <loc>http://localhost:8080/API/collection/VX-1000/</loc>
  <id>VX-1000</id>
  <!-- Change the name of the collection to "Final name" -->
  <name>Final name</name>

  <!-- Remove item VX-3 -->
  <content mode="remove">
    <id>VX-3</id>
    <type>item</type>
  </content>

  <!-- Add library VX*30 after library VX*20 with metadata-->
  <content mode="add" after="VX*20">
    <id>VX*30</id>
    <type>library</type>
    <metadata>
        <field>
            <key>AddedBy</key>
            <value>User</value>
        </field>
    </metadata>
  </content>

  <!-- Add the all items from library VX*10 (which are VX-97 and VX-98)
  after item VX-2 -->
  <content mode="add" addItems="true" after="VX-2">
    <id>VX*10</id>
    <type>library</type>
  </content>

  <!-- Move library VX*20 before VX*10, metadata won't be updated for specified entity when mode="move" -->
  <content mode="move" before=VX*10>
    <id>VX*20</id>
    <type>library</type>
  </content>

  <!-- Note that first we added library VX*30 after library VX*20 then
  we moved library VX*20 before VX*10:
  [VX*10, VX*20] -> [VX*10, VX*20, VX*30] -> [VX*20, VX*10, VX*30] -->
</CollectionDocument>
<CollectionDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <id>VX-1000</id>
    <name>Final name</name>
    <content>
        <id>VX-2</id>
        <type>item</type>
        <uri>http://localhost:8080/API/item/VX-2</uri>
    </content>
    <content>
        <id>VX-97</id>
        <type>item</type>
        <uri>http://localhost:8080/API/item/VX-97</uri>
    </content>
    <content>
        <id>VX-98</id>
        <type>item</type>
        <uri>http://localhost:8080/API/item/VX-98</uri>
    </content>
    <content>
        <id>VX-1</id>
        <type>item</type>
        <uri>http://localhost:8080/API/item/VX-1</uri>
    </content>
    <content>
        <id>VX*20</id>
        <type>library</type>
        <uri>http://localhost:8080/API/library/VX*20</uri>
    </content>
    <content>
        <id>VX*10</id>
        <type>library</type>
        <uri>http://localhost:8080/API/library/VX*10</uri>
    </content>
    <content>
        <id>VX*30</id>
        <type>library</type>
        <uri>http://localhost:8080/API/library/VX*30</uri>
        <metadata>
            <field>
                <key>AddedBy</key>
                <value>User</value>
            </field>
        </metadata>
    </content>
    <content>
        <id>VX-100</id>
        <type>collection</type>
        <uri>http://localhost:8080/API/collection/VX-100</uri>
    </content>
    <content>
        <id>VX-200</id>
        <type>collection</type>
        <uri>http://localhost:8080/API/collection/VX-200</uri>
    </content>
</CollectionDocument>

Collection metadata

Metadata can be set on collections, just like with items.

See Metadata.

Searching for collections

Searching collections behaves much like Search.

Search for collections

PUT /collection

Searches for collections that matches the query.

Matrix Parameters:
 
  • first – Integer. The index of the first collection. Default is 1.
  • cursor

    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.

    Only metadata searches in the generic interval supports cursor.

  • number – Integer. The number of collections to retrieve. Default is 100.
Query Parameters:
 
  • count
    • true (default) - Return hits in result.
    • false - Do not return hits in result, in order to produce results faster.
  • content – Optional comma-separated list of addition content to retrieve. Possible values are: metadata, 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.
  • 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.
  • 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.
  • conflict
    • yes (default) - Include all metadata conflicts, unresolved.
    • no - Return conflicts resolved according to field rules.
  • include – A list of keys. Includes additional field specific data. Additionally, if set to type the type definition of the field will be retrieved.
  • defaultValue
    • true - For unset fields, return default values.
    • false (default) - Do not return default values.
  • includeTransientMetadata
    • true (default) - Include transient metadata.
    • false - Do not include transient metadata in response.
  • includeValues – Return the value enumeration for each metadata field.
  • terse
    • yes - Return metadata in terse format.
    • no (default) - Return metadata in verbose format.
  • 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.
Accepts:
Produces:
Role:

_collection_read

Retrieve search history

New in version 4.0.3.

GET /collection/history

Retrieves a list of searches made by a particular user, include “Collection 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. If set, only searches made after this date will be retrieved.
  • maxResults – 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.
Status Codes:
  • 400 Bad request – The request was malformed.
Produces:
Role:

_item_search

Ordering collections

Collections will return their elements in the same order for every request.

Changed in version 4.4: Queries on collection items will now return items in creation order by default. See indexCollectionItemOrder on how to revert back to using the insert/custom collection item ordering.

Reordering collection elements

POST /collection/(collection-id)/order

Changes the order of the elements. Note that the reordering elements are parsed and applied in the sequence that they are supplied.

Accepts:
Produces:
  • application/xml, application/jsonCollectionDocument containing the elements in their new order.
  • text/plain – CRLF-delimited list of ids
Role:

_collection_write

Example

Starting with an unordered collection of items, we will sort it according to item id. At the start it contains items [VX-7, VX-8, VX-5, VX-6].

GET /collection/VX-1
<CollectionDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <loc>http://localhost:8080/API/collection/VX-1/VX-1</loc>
  <id>VX-1</id>
  <content>
    <id>VX-7</id>
    <uri>http://localhost:8080/API/item/VX-7</uri>
    <type>item</type>
  </content>
  <content>
    <id>VX-8</id>
    <uri>http://localhost:8080/API/item/VX-8</uri>
    <type>item</type>
  </content>
  <content>
    <id>VX-5</id>
    <uri>http://localhost:8080/API/item/VX-5</uri>
    <type>item</type>
  </content>
  <content>
    <id>VX-6</id>
    <uri>http://localhost:8080/API/item/VX-6</uri>
    <type>item</type>
  </content>
</CollectionDocument>
POST /collection/VX-1/order
Content-Type: application/xml

<CollectionReorderDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <!-- Find the current first element and put VX-5 first -->
    <item id="VX-5" before="VX-7"/>

    <!-- Add the other elements after VX-5 in sequence -->
    <item id="VX-6" after="VX-5"/>
    <item id="VX-7" after="VX-6"/>
    <item id="VX-8" after="VX-7"/>
</CollectionReorderDocument>
<CollectionDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <id>VX-1</id>
  <content>
    <id>VX-5</id>
    <uri>http://localhost:8080/API/item/VX-5</uri>
    <type>item</type>
  </content>
  <content>
    <id>VX-6</id>
    <uri>http://localhost:8080/API/item/VX-6</uri>
    <type>item</type>
  </content>
  <content>
    <id>VX-7</id>
    <uri>http://localhost:8080/API/item/VX-7</uri>
    <type>item</type>
  </content>
  <content>
    <id>VX-8</id>
    <uri>http://localhost:8080/API/item/VX-8</uri>
    <type>item</type>
  </content>
</CollectionDocument>

Folder mapped collections

It is possible to map a Vidispine collection to a folder on the file system. This means that any files of items part of the collection will be stored in a sub-folder with the same name as the collection. For a collection marked as mapped to a folder, some additional rules are enforced when it comes to collection relationships:

  • A folder mapped collection can have at most one folder mapped parent collection.
  • An item can have at most one folder mapped parent collection.

That is, the same rule that applies to files on a traditional file system.

Note

Adding an item to a folder mapped collection will not move the item files to the corresponding folder immediately as the file movement is done asynchronously in the background.

Mark a collection as folder mapped

PUT /collection/(collection-id)/map-to-folder

Marks collection collection-id as mapped to folder. Files in child items will be moved to the corresponding folder in the storages.

Role:_collection_write

Un-mark a collection as folder mapped

DELETE /collection/(collection-id)/map-to-folder

Marks collection collection-id as not mapped to folder. Files in child items will be moved to the root directory in the storages.

Role:_collection_write

Report that the folder name has changed on disk

PUT /collection/(collection-id)/folder-name

If the folder name has been changed by a user or an external program, it can be reported to Vidispine with this command. The affected file entities in the database will then be updated with the new path, and the collection name will be changed.

Query Parameters:
 
  • name – The new name of the folder (required).
Produces:
  • text/plain – “OK”
Role:

_collection_write