Items

Managing items

Retrieve a list of all items

GET /item
Content Parameters:
 

See Retrieving item information

Query Parameters:
 
  • result
    • list (default) - Return a list of items.
    • library - Create a library with the matching items.
  • q – XML/JSON, ItemSearchDocument. Only with GET.
  • count
    • true (default) - Return hits in result.
    • false - Do not return hits in result, in order to produce results faster.
Matrix Parameters:
 
  • library – Restricts search to within library, Identifiers. Default is *, all items.
  • first – Integer, from resulting list of items, start return list from specified offset. Default is 1, start return list from beginning.
  • number – Integer, set a limit on maximum number of hits. Default 100.
  • libraryId – If set, the library identified by this id will be used instead of creating a new library.
  • autoRefresh – See Self-refreshing libraries. Defaults to false.
  • updateMode – See Self-refreshing libraries. Defaults to MERGE.
  • updateFrequency – See Self-refreshing libraries. Defaults to no periodic updates.
Produces:
  • application/xml, application/jsonItemListDocument
  • text/plain – CRLF-delimited list of ids or URLs
Role:

_item_search

Semantics

Returns a list of all items. This request is the same as performing an empty search.

Get information about a single item

GET /item/(item-id)
Matrix Parameters:
 
  • starttc
    • true - Interval is given relative to start timecode of item.
    • false (default) - Interval is 0-based.
Query Parameters:
 
  • noauth-url – Whether to return thumbnail URLs not requiring authentication. Default value is false
  • baseURI – Which base URI to use for the thumbnail URLs.
Produces:

Semantics

Returns information about a single item.

Delete a single item

Deleting an item means removing the item’s id, its metadata, shapes, and physical files.

DELETE /item/(item-id)
Query Parameters:
 
  • keepShapeTagMedia – Optional comma-separated list of shape tags whose files will not be deleted.
  • keepShapeTagStorage – Optional comma-separated list of storage ids whose files will not be deleted.

Semantics

Marks the item as being deleted, meaning it will not be returned in search results. The actual removement from the database is done approximately once every minute. Also, all files associated with the item is marked as TO_BE_DELETED, meaning they will be deleted by the storage supervisor, but not sooner than all jobs involving the actual file has finished.

By specifying keepShapeTagMedia and/or keepShapeTagStorage, the files associated with the item is not deleted, but simply unassociated with the item.

If only keepShapeTagMedia is given, all files belonging to shapes of the item with any of the given shape tags are preserved.

If only keepShapeTagStorage is given, all files belonging to the item residing on the given storages are preserved. If both keepShapeTagMedia and keepShapeTagStorage is given, all files which both belongs to the specified shapes and storages are preserved.

New in version 4.3.2.

If any of keepShapeTagMedia or keepShapeTagStorage contains a value *, then no files will be removed.

Search items

PUT /item
Content Parameters:
 

See Retrieving item information

Query Parameters:
 
  • result
    • list (default) - Return a list of items.
    • library - Create a library with the matching items.
  • q – XML/JSON, ItemSearchDocument. Only with GET.
  • count
    • true (default) - Return hits in result.
    • false - Do not return hits in result, in order to produce results faster.
Matrix Parameters:
 
  • library – Restricts search to within library, Identifiers. Default is *, all items.
  • first – Integer, from resulting list of items, start return list from specified offset. Default is 1, start return list from beginning.
  • number – Integer, set a limit on maximum number of hits. Default 100.
  • libraryId – If set, the library identified by this id will be used instead of creating a new library.
  • autoRefresh – See Self-refreshing libraries. Defaults to false.
  • updateMode – See Self-refreshing libraries. Defaults to MERGE.
  • updateFrequency – See Self-refreshing libraries. Defaults to no periodic updates.
Produces:
  • application/xml, application/jsonItemListDocument
  • text/plain – CRLF-delimited list of ids or URLs
Role:

_item_search

Semantics

Performs an item search. If the result query parameter is set to library a new library is created, which can be used to further refine the search, using the library parameter.

Note that 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, start a job using Listing items in batch to get all items at once.

Example

GET /item?result=library
Content-Type: application/xml

<ItemSearchDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <field>
    <name>product_category</name>
    <value>tv</value>
  </field>
</ItemSearchDocument>
<ItemListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <library>VX*1233</library>
  <item>VY-1233</item>
  <item>VY-1234</item>
  <item>VX-7888</item>
</ItemListDocument>
PUT /item;library=VX*1233
Content-Type: application/xml

<ItemSearchDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <field>
    <name>created</name>
    <range>
      <value>2014-05-30T00:00:00+0200</value>
      <value>2014-06-03T07:30:00+0200</value>
    </range>
  <field>
</ItemSearchDocument>
<ItemListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <library>VX*1234</library>
  <item>VY-1233</item>
  <item>VX-7888</item>
</ItemListDocument>

Search history

Retrieve search history

GET /item/history

Retrieves a list of searches made by a particular user, including “item search” and “Item and collection search”. The results are ordered according to timestamp, with the latest searches being first. Duplicate queries will not be retrieved.

Query Parameters:
 
  • start – Optional ISO8601 date. 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 – The name of the user that has performed the searched. If not specified, the user performing the request will be selected.
Produces:
  • application/xml, application/jsonSearchHistoryListDocument.
Role:

_item_search

Re-index item

PUT /item/(item-id)/re-index

Queues a single item for re-index.

See Re-indexing metadata if you wish to reindex all items in the system.

Listing items in batch

Creating an item list job

POST /item/list

Starts a new job that goes through all the items available to the user/group and outputs a file to the supplied URI.

If no user and no group is supplied, all items will be retrieved. 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.
  • username – Filter items according to the access of the specified user.
  • groupname – Filter items according to the access of the specified group.
  • field – A comma-separated list of metadata fields to include in the result.
  • outputFormat – Specifies the output format. Valid values are xml (default) and csv.
  • data – Specifies any additional data that should be included with the metadata fields.
  • 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:

_administrator

Example

POST /item/list?field=title,durationSeconds&username=admin&destinationUri=file:/home/user/output.csv&outputFormat=csv
Content-Type: application/xml

<JobDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <jobId>VX-64</jobId>
  <user>admin</user>
  <started>2010-11-29T11:12:55.768+01:00</started>
  <status>READY</status>
  <type>LIST_ITEMS</type>
  <priority>MEDIUM</priority>
</JobDocument>
$ cat /home/user/output.csv
"itemId","format","fileSize","downloads","metadataField-title","metadataField-durationSeconds"
"VX-22","mxf","10000000","1","","180.0"
"VX-18","mp3,aac","5876698,4253659","0","","212.242695"
"VX-12","flv","23939202","5","This is ""the"" title.","142.124698"
"VX-8","flv","5684452","3","","12.412487"

Parent collections

List collections that contain an item

GET /item/(item-id)/collections
Produces:
  • application/xml, application/jsonURIListDocument containing the collection ID of all collections that includes the item, and that the calling user has read access to.
Role:

_item_read

Example

GET /item/VX-94/collections
<URIListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <uri>VX-23</uri>
  <uri>VX-64</uri>
</URIListDocument>