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

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

Produces:
  • application/xml, application/jsonJobDocument containing library delete job.
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.

Query Parameters:
 
  • content – See Retrieving item information
  • noauth-url – Whether to return thumbnail URLs not requiring authentication. Default value is false
  • baseURI – Which base URI to use for the thumbnail URLs.
Matrix Parameters:
 
  • starttc
    • true - Interval is given relative to start timecode of item.
    • false (default) - Interval is 0-based.
  • 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.
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:
 
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>