Libraries

A library can be seen as a lightweight collection that is deleted on a regular basis if it is not being used. Libraries can only contain items.

Managing libraries

Retrieve a list of all libraries

GET /library

Retrieves a list of the ids of all known libraries.

Matrix Parameters:
 
  • first – Integer, from resulting list of items, start return list from specified offset. Default is 1, start return list from beginning.
  • number – Integer, set a limit on maximum number of hits. Default 100.
  • autoRefresh

    Optional boolean value, only list libraries with the specified auto refresh status.

    New in version 4.2.3.

  • frequencyFrom

    Optional integer value, only list libraries whose update frequency is greater than it.

    New in version 4.2.3.

  • frequencyTo

    Optional boolean value, only list libraries whose update frequency is less than it.

    New in version 4.2.3.

  • updateMode

    Optional string value, only list libraries with the specified update mode.

    New in version 4.2.3.

Produces:
  • application/xml, application/jsonURIListDocument containing the ids of all the libraries.
  • text/plain – CRLF-delimited list of ids
Role:

_library_read

Example

GET /library
<URIListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <uri>VX*48</uri>
   <uri>VX*49</uri>
   <uri>VX*45</uri>
</URIListDocument>

Create a library

POST /library

Creates a library and returns the id of the created library.

Query Parameters:
 
  • externalId – An external identifier to assign to the library.
Accepts:
  • application/xml, application/jsonItemListDocument that contains the ids of any items that should be added to the library
Produces:
  • application/xml, application/jsonURIListDocument containing the id of the created library.
  • text/plain – CRLF-delimited list of ids
Status Codes:
  • 400 – If the external id is already in use.
Role:

_library_write

Example

POST /library
Content-Type: application/xml

<ItemListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <item id="VX-250"/>
   <item id="VX-1000"/>
</ItemListDocument>
<URIListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <uri>VX*48</uri>
</URIListDocument>

Delete a library

DELETE /library/(library-id)

Deletes the library with the specified id.

Query Parameters:
 
  • async
    • true - Start a DELETE_LIBRARY job that removes the library.
    • false (default) - Remove the library immediately.
  • notification – See Notifications . (Optional)
  • notificationData – See Notifications . (Optional)
  • priority – The priority to assign to the job. Default is MEDIUM .
  • jobmetadata – Additional information for the job task. See Special job metadata values
Produces:
  • application/xml, application/jsonJobDocument containing library delete job.
Status Codes:
  • 202 – The library will be removed by the returned job.
  • 200 – The library has been deleted.
Role:

_library_write

Example

DELETE /library/VX*51

Library settings

Retrieve library settings

GET /library/(library-id)/settings

Retrieves the settings and status of a library.

Produces:
Role:

_library_read

Example

GET /library/VX*67/settings HTTP/1.1
<LibrarySettingsDocument>
   <id>VX*67</id>
   <username>admin</username>
   <updateMode>REPLACE</updateMode>
   <autoRefresh>true</autoRefresh>
   <query>
      <field>
      <name>originalWidth</name>
      <range>
         <value>640</value>
         <value>720</value>
      </range>
      </field>
   </query>
</LibrarySettingsDocument>

Update library settings

New in version 4.0.3.

PUT /library/(library-id)/settings

Update the settings of a library.

Accepts:
Role:

_library_write

Library content

Retrieve library content

GET /library/(library-id)

Returns the items together with any requested data.

Matrix Parameters:
 
  • starttc
    • true - Interval is given relative to start timecode of item.
    • false (default) - Interval is 0-based.
Query Parameters:
 
  • first – Integer, from resulting list of items, start return list from specified offset. Default is 1, start return list from beginning.
  • number – Integer, set a limit on maximum number of hits. Default 100.
  • count
    • true (default) - Return hits in result.
    • false - Do not return hits in result, in order to produce results faster.
  • noauth-url
    • true Return URIs that do not need authentication.
    • false (default) Return normal URIs
  • baseURI – Which base URI to use for the thumbnail URLs.
  • p

    Comma separated list of paths specifying the content to include. Overrides the content and filter parameters. See Content paths.

    New in version 4.5.

  • content – Comma-separated list of the types of content to retrieve, possible values are metadata, uri, shape, poster, thumbnail, access, merged-access, external.
  • interval

    Comma-separated list

    • time-span - Filter out metadata, return only metadata for specified time span.
    • generic - Return all non-timed metadata.
    • all (default) - Return all metadata, same as interval=generic,-INF-+INF
  • field

    Comma-separated list.

    • field-name - Return specified field.
    • field-name ”:” new-name - Return specified field, renamed to a new name in return value.
    • “-” field-name - Exclude specified field.
    • (default) - Return all fields.
  • group

    Comma-separated list.

    • group-name - Return specified group.
    • group-name + - Return specified group and subgroups.

      New in version 4.1.

    • group-name : new-name - Return specified group, renamed to a new name in return value.
    • - group-name - Exclude specified group.
    • (default) - Return all groups.
  • language

    Comma separated list.

    • language-tag - Return metadata for specific language, e.g. en_US. Wildcards may be used, e.g. *_CA for both Canadian French and Canadian English.
    • none - Return all metadata without language specification.
    • all (default) - Return all metadata, with or without language specification.
  • sampleRate – Convert all outgoing time instants to specified rate. NB! Time codes which cannot be expressed in an integer number of samples will be returned as a decimal number, with risk of losing precision.
  • track

    Comma separated list.

    • track-type track-number - Return metadata for specified track. Example of track is A2.
    • track-type t1 - t2 - Return metadata for specified track interval, e.g. A2-4.
    • track-type * - Return metadata for all tracks of specified type, e.g. A*.
    • generic - Return all non-tracked metadata.
    • all (default) - All metadata, with or without track specification, are returned.
  • include – A list of keys. Includes additional field specific data. See Field metadata. Additionally, if set to type the type definition of the field will be retrieved.
  • includeValues – Return the value enumeration for each metadata field.
  • conflict
    • yes (default) - Include all metadata conflicts, unresolved.
    • no - Return conflicts resolved according to field rules.
  • terse
  • defaultValue
    • true - For unset fields, return default values. See Default values.
    • false (default) - Do not return default values.
  • includeTransientMetadata
    • true (default) - Include transient metadata, see Transient metadata.
    • false - Do not include transient metadata in response.
  • revision – Optional revision, specifying which metadata to display. Only used if requesting a single item or collection.
  • mergedType – The type of operation to check for.
  • mergedPermission – The lowest required permission level.
  • mergedExtradata – Any possible extradata.
  • uriType – Optional comma-separated list of format types (container format) to return.
  • scheme – URI scheme to return.
  • storageType – Only return URIs for files from storages of this type. See Storages.
  • methodType

    Optional type of access method. See Storages.

    • AUTO - Gives an APInoauth URI to the media. Access to file is tunneled through Vidispine.
    • AZURE_SAS - If the storage schema is azure:// you can get direct access to the media. The resulting URI will not tunnel through Vidispine but rather point directly to the media location at the azure storage.
  • methodMetadata – Optional metadata used with storage method. See Storages.
  • tag – A URI parameter, see Get item URI.
  • version – Optional integer, specifying which essence version to return for shapes. If special value all, display all versions. If special value latest (default), display latest version of shapes.
  • closedFiles – A URI parameter, see Get item URI.
Produces:
  • application/xml, application/jsonItemListDocument containing the items together with the requested data.
Role:

_library_read

Example

GET /library/VX*48/?content=access HTTP/1.1
<ItemListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <item id="VX-250">
      <access>
         <type>GENERIC</type>
         <permission>ALL</permission>
      </access>
      <access>
         <type>METADATA</type>
         <permission>ALL</permission>
      </access>
      <access>
         <type>ID</type>
         <permission>ALL</permission>
      </access>
      <access>
         <type>URI</type>
         <permission>ALL</permission>
      </access>
   </item>
   <item id="VX-1000">
      <access>
         <type>GENERIC</type>
         <permission>ALL</permission>
      </access>
      <access>
         <type>METADATA</type>
         <permission>ALL</permission>
      </access>
      <access>
         <type>ID</type>
         <permission>ALL</permission>
      </access>
      <access>
         <type>URI</type>
         <permission>ALL</permission>
      </access>
   </item>
</ItemListDocument>

Add multiple items to a library

PUT /library/(library-id)

Adds all the items specified in the document to the library.

Accepts:
  • application/xml, application/jsonItemListDocument that contains the item ids.
Role:

_library_write

Example

PUT /library/VX*48
Content-Type: application/xml

<ItemListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <item id="VX-1000"/>
   <item id="VX-250"/>
</ItemListDocument>
200 OK

Add a specific item to a library

PUT /library/(library-id)/(item-id)

Adds the specified item to the library.

Role:_library_write

Example

PUT /library/VX*48/VX-251
200 OK

Remove a specific item from a library

DELETE /library/(library-id)/(item-id)

Removes the specified item from the library.

Role:_library_write

Example

DELETE /library/VX*48/VX-251
200 OK

Modify metadata of the items in a specific library

PUT /library/(library-id)/item-metadata

Modify metadata of the items in a specific library

Query Parameters:
 
Accepts:
  • application/xml, application/jsonMetadataDocument the metadata to apply to the items.
Produces:
Role:

_library_write

Listing library items in batch

New in version 4.5.

Creating an item list job

POST /library/(library-id)/list

Starts a new job that goes through all the items in the specific library and outputs a file to the supplied URI.

The output format depends on the specified parameter, if set to XML an ItemListDocument will be produced. Furthermore if an XSLT is given the ItemListDocument will be transformed.

Query Parameters:
 
  • destinationUri – The URI to output the CSV file to.
  • outputFormat – Specifies the output format. Valid values are xml (default) and csv.
  • field – A comma-separated list of metadata fields to include in the result.
  • data – Specifies any additional data that should be included with the metadata fields.
  • p – Comma-separated list of paths specifying the content to include. Overrides the field and data parameters. Only supported for XML output. See Content paths.
  • notification – See Notifications . (Optional)
  • notificationData – See Notifications . (Optional)
  • priority – The priority to assign to the job. Default is MEDIUM .
  • jobmetadata – Additional information for the job task. See Special job metadata values
Accepts:
  • application/xslt – An optional XSLT capable of transforming ItemListDocument.
Produces:
Role:

_library_read

Example

POST /library/VX*75/list?p=id,shape.containerComponent.duration&destinationUri=file:/home/user/output.xml
Content-Type: application/xml

<JobDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <jobId>VX-121</jobId>
  <user>admin</user>
  <started>2016-02-21T10:11:42.998+01:00</started>
  <status>READY</status>
  <type>LIST_ITEMS</type>
  <priority>MEDIUM</priority>
</JobDocument>
$ xmllint --format /home/user/output.xml
<?xml version="1.0"?>
<ItemListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <item xmlns="http://xml.vidispine.com/schema/vidispine" id="VX-47">
    <shape>
      <containerComponent>
        <duration>
          <samples>1871720000</samples>
          <timeBase>
            <numerator>1</numerator>
            <denominator>1000000</denominator>
          </timeBase>
        </duration>
      </containerComponent>
    </shape>
  </item>
  <item xmlns="http://xml.vidispine.com/schema/vidispine" id="VX-48">
    <shape>
      <containerComponent>
        <duration>
          <samples>1871763000</samples>
          <timeBase>
            <numerator>1</numerator>
            <denominator>1000000</denominator>
          </timeBase>
        </duration>
      </containerComponent>
    </shape>
  </item>
</ItemListDocument>