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

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/OpenSearch 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:
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/jsonCollectionDocument
  • text/plain – CRLF-delimited list of ids
Status Codes:
  • 409 – 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:
Produces:
  • application/xml, application/jsonCollectionDocument
  • text/plain – CRLF-delimited list of ids
Status Codes:
  • 409 – 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

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/jsonCollectionDocument
  • text/plain – CRLF-delimited list of ids
Role:

_collection_read

List all items of a collection

GET /collection/(collection-id)/item

List all 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/OpenSearch 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/jsonItemListDocument
  • text/plain – CRLF-delimited list of ids or URLs
  • application/xml, application/jsonItemListDocument
  • text/plain – CRLF-delimited list of ids or URLs.
Role:

_collection_read

Role:

_metadata_read (content=metadata)

Role:

_item_uri (content=uri)

Role:

_thumbnail_read (content=poster and content=thumbnail)

Role:

_accesscontrol_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.
  • holdJob (boolean) – If set to true, the job will be created in a HOLD state. Default is false.
Accepts:
  • application/xslt – An optional XSLT capable of transforming ItemListDocument.
Produces:
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/jsonURIListDocument
  • 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.

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.

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/OpenSearch 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/jsonItemListDocument
  • text/plain – CRLF-delimited list of ids or URLs
Accepts:
Status Codes:
Role:

_collection_read

Role:

_metadata_read (content=metadata)

Role:

_item_uri (content=uri)

Role:

_thumbnail_read (content=poster and content=thumbnail)

Role:

_accesscontrol_read (content=access and content=merged-access)

Role:

_item_id_read (content=external)

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

PUT /collection/VX-1000/VX*10?type=library&metadata=addedBy%3dadmin&metadata=dateAdded%3dFeb 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 (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:
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.

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/OpenSearch 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:
Produces:
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:
Role:

_item_search

Search collection by metadata group

New in version 22.4.

PUT /collection/metadata-group

Search the metadata groups within collections, and group the results by their owner collections.

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.
  • first (integer) – From the resulting list of items, start return list from specified offset. Default is 1, start return list from beginning.
  • 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.
  • 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.
Accepts:
Produces:
Role:

_collection_read

PUT /collection/metadata-group
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MetadataGroupSearchDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <operator operation="OR">
    <field>
      <name>title</name>
      <value>goal</value>
    </field>
    <field>
      <name>title</name>
      <value>foul</value>
    </field>
  </operator>
</MetadataGroupSearchDocument>

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/OpenSearch 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:
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/OpenSearch 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:
Produces:
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:
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

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.
  • holdJob (boolean) – If set to true, the job will be created in a HOLD state. Default is false.
  • 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:
Role:

_collection_write