Collection reference [VC 21.3.1 GEN]

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

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

Managing collections

List all collections

GET /collection

Retrieves a list of all known collections.

Query Parameters:	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. content (string) – Comma-separated list of additional content to retrieve. Valid values are: `metadata`, `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. 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. 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. conflict (string) – `yes` (default) - Include all metadata conflicts, unresolved. `no` - Return conflicts resolved according to field rules. 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. 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. includeValues (boolean) – Return the value enumeration for each metadata field. terse (string) – `yes` - Return metadata in terse format. `no` (default) - Return metadata in verbose format. revision (string) – Specifying what revision of metadata 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.
Produces:	application/xml, application/json – CollectionListDocument text/plain – CRLF-delimited list of ids
Role:	_collection_read

Create a collection

POST /collection

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

Query Parameters:	name (string) – Name of the collection. externalId (string) – An external identifier to assign to the collection. settings (string) – Pre-configured import settings.
Produces:	application/xml, application/json – CollectionDocument 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.

Query Parameters:	name (string) – Name of the collection. externalId (string) – An external identifier to assign to the collection. settings (string) – Pre-configured import settings.
Accepts:	application/xml, application/json – CollectionDocument
Produces:	application/xml, application/json – CollectionDocument 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.
Role:	_collection_write

Delete multiple collections

DELETE /collection

Delete multiple collections.

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

Query Parameters:	id (string) – Required. Comma-separated list of collection ids or external ids.
Status Codes:	200 OK – The collections are deleted. 404 Not found – Could not find the collection.
Role:	_collection_write

Example

NONE

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

Update collection name

PUT /collection/(collection-id)/rename

Sets the name of the collection with the Identifiers collection-id.

Query Parameters:	name (string) – Required. New name of the collection.
Role:	_collection_write

Collection content

Retrieve 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 (string) – Comma-separated list of additional content to retrieve. Valid values are: `metadata`, `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. 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. 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. conflict (string) – `yes` (default) - Include all metadata conflicts, unresolved. `no` - Return conflicts resolved according to field rules. 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. 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. includeValues (boolean) – Return the value enumeration for each metadata field. terse (string) – `yes` - Return metadata in terse format. `no` (default) - Return metadata in verbose format. revision (string) – Specifying what revision of metadata 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. children (string) – Comma-separated list of types to include in the result. Default is to return everything. `collection` - Return collections contained in this collection. `item` - Return items contained in this collection. `library` - Return libraries contained in this collection. New in version 4.16.6.
Status Codes:	404 Not found – Could not find the collection.
Produces:	application/xml, application/json – CollectionDocument 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.

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

Create an item list job for the collection

POST /collection/(collection-id)/item/list

Starts a new job that creates a list of all items in the collection, similarly to listing all items.

Query Parameters:	recursive (boolean) – will include items in child collections recursively. Default is false. destinationUri (string) – Required. The URI to output the CSV file to. username (string) – Filter items according to the access of the specified user. 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

Retrieve the ancestors of a collection

GET /collection/(collection-id)/ancestor

Retrieves the ids of all ancestors of the collection.

Produces:	application/xml, application/json – URIListDocument text/plain – CRLF-delimited list of ids
Role:	_collection_read

Search for items within a collection

PUT /collection/(collection-id)/item

Performs a search among the items in the specified collection.

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.

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.

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 (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
Status Codes:	400 Bad request – Either the ItemSearchDocument or a parameter was invalid.
Role:	_collection_read
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`)

Example

NONE

GET /collection/VX-76/item
Accept: application/xml

HTML/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 (string) – `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. reference (string) – an optional UUID of the relation between the collection and the added entity mode (string) – `REPLACE` (default) - Existing relations between the collection and the added entity are removed before entity is added `ADD` - Entity is added to the list of relation, the entity can appear multiple times before (string) – an optional UUID of where in the list of relations the new relation should be inserted. The relation is inserted before the relation given. If no UUID is give, the relation is added at the end. addItems (boolean) – `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 (string[]) – 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`).
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

NONE

PUT /collection/VX-1000/VX*10?type=library&metadata=addedBy%3dadmin&metadata=dateAdded%3dFeb 2, 2018

NONE

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 (string) – `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. reference (string) – an optional UUID of the relation to be deleted. Can be used to delete a specific instance of relation between the collection and the referenced entity.
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

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 (boolean) – `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:	application/xml, application/json – CollectionDocument that contains the entity ids.
Produces:	application/xml, application/json – CollectionDocument 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.

NONE

GET /collection/VX-1000

HTML/XML

<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>

NONE

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>

HTML/XML

<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.

NONE

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>

HTML/XML

<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.

Query Parameters:	first (integer) – The index of the first collection. Default is `1`. 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 collections to retrieve. Default is `100`. count (boolean) – `true` (default) - Return hits in result. `false` - Do not return hits in result, in order to produce results faster. content (string) – Comma-separated list of additional content to retrieve. Valid values are: `metadata`, `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. 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. 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. conflict (string) – `yes` (default) - Include all metadata conflicts, unresolved. `no` - Return conflicts resolved according to field rules. 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. 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. includeValues (boolean) – Return the value enumeration for each metadata field. terse (string) – `yes` - Return metadata in terse format. `no` (default) - Return metadata in verbose format. revision (string) – Specifying what revision of metadata 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.
Accepts:	application/xml, application/json – ItemSearchDocument
Produces:	application/xml, application/json – CollectionListDocument
Role:	_collection_read

Retrieve the search history

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 (string) – 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.
Status Codes:	400 Bad request – The request was malformed.
Produces:	application/xml, application/json – SearchHistoryDocument
Role:	_item_search

Retrieve the child-collections of a collection

GET /collection/(collection-id)/collection

Returns the child collections of collection with id collection-id.

Query Parameters:	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. content (string) – Comma-separated list of additional content to retrieve. Valid values are: `metadata`, `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. 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. 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. conflict (string) – `yes` (default) - Include all metadata conflicts, unresolved. `no` - Return conflicts resolved according to field rules. 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. 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. includeValues (boolean) – Return the value enumeration for each metadata field. terse (string) – `yes` - Return metadata in terse format. `no` (default) - Return metadata in verbose format. revision (string) – Specifying what revision of metadata 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.
Status Codes:	404 Not found – Could not find the collection.
Produces:	application/xml, application/json – CollectionListDocument text/plain – CRLF-delimited list of ids
Role:	_collection_read

Search the child-collections of a collection

PUT /collection/(collection-id)/collection

Searches for collections that matches the query, limited to the child-collections of collection-id.

Query Parameters:	first (integer) – The index of the first collection. Default is `1`. 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 collections to retrieve. Default is `100`. count (boolean) – `true` (default) - Return hits in result. `false` - Do not return hits in result, in order to produce results faster. content (string) – Comma-separated list of additional content to retrieve. Valid values are: `metadata`, `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. 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. 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. conflict (string) – `yes` (default) - Include all metadata conflicts, unresolved. `no` - Return conflicts resolved according to field rules. 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. 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. includeValues (boolean) – Return the value enumeration for each metadata field. terse (string) – `yes` - Return metadata in terse format. `no` (default) - Return metadata in verbose format. revision (string) – Specifying what revision of metadata 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.
Accepts:	application/xml, application/json – ItemSearchDocument
Produces:	application/xml, application/json – CollectionListDocument
Role:	_collection_read

Ordering collections

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

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.

Reorder 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:	application/xml, application/json – CollectionReorderDocument containing the changes to the order.
Produces:	application/xml, application/json – CollectionDocument 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].

NONE

GET /collection/VX-1

HTML/XML

<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>

NONE

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>

HTML/XML

<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.

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

Unmark 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 (string) – Required. The new name of the folder.
Produces:	text/plain – “OK”
Role:	_collection_write

Training datasets

POST /collection/(collection-id)/train

Train a collection to a model using a VidiNet Cognitive Service. The model can then be used for running analyses.

New in version 21.3.

Query Parameters:	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. resourceId (string) – Required. The VidiNet resource to use for training. callbackId (string) – Required. The callback resource id to use for finding and running callback scripts.
Produces:	application/xml, application/json – JobDocument
Role:	_collection_write