Vidispine REST API
  • Introduction and data model
    • Entities in Vidispine
      • Item
      • Shape
      • Component
      • File and storage
      • Library
      • Collection
    • RESTful API
      • Some basics in the RESTful API
    • Common elements in the API
      • Identifiers
      • Boolean operators
      • Text/plain formatting
    • Time representation
      • Time bases
      • Time codes
      • Time intervals
      • Time durations
      • Time span
    • Content paths
      • Paths
      • Aliases
    • Constants
  • Items and Metadata
    • Imports
      • Importing items
      • Steps of import operation
      • Transcoding
      • Notifications
      • Adjusting import
    • Exports
      • Exporting items
      • Export locations
      • Export templates
    • Item metadata
      • Fields
      • Field groups
      • Metadata schema
      • Hierarchical metadata
      • Metadata inheritance
      • Versioning
      • Structure of metadata
      • Metadata defined by the systems
    • Searching for items (and collections)
      • Searching in Vidispine
      • Search history
      • Queries
      • Filters
      • Joins
      • Highlighting
      • Sorting
      • Faceting
      • Spell checking
      • Autocompletion
      • Search Boost
    • Caching
      • Search result caching
    • Metadata projections
      • Projections
      • XSLT 2.0
      • Job Information
      • Auto-projection rules
      • Auto-projection using JavaScript
      • Auto-projection using XSLT
    • Metadata migrations
      • Migration operations
      • Migration definition
    • Metadata datasets
      • Defining the dataset
      • Create the dataset
      • Configure metadata fields
      • Updating metadata
      • Searching for dataset values
      • Validation of metadata values
      • Retrieving allowed values
    • Subtitles
      • Subtitle metadata fields and groups
      • Rendering subtitles in a sequence
      • SCC support
      • TTML support
    • Examples
      • Creating fields/groups, modifying and moving metadata
      • Defining a metadata schema
  • Collections and Libraries
    • Collections
      • Creating collections
      • Searching for collections
      • Ordering collections
      • Update collection content
      • Partial update collection content
      • Multiple relations between same entities
      • Metadata on collection to entity relations
      • Collections as folders
      • Representative thumbnails
    • Libraries
      • Creating libraries
      • Automatic deletion
      • Self-refreshing libraries
      • Restricting access to items
      • Storage rules on libraries
  • Shapes, Components and Transcoding
    • Item shapes
      • Shapes
      • Essence versions
      • Transcoding
      • Thumbnailing
      • Analyzing media
    • Shape tags and presets
      • Transcode presets
      • Scripting transcode presets
      • Transcode preset elements
      • Custom settings
    • Common presets
      • H.264
      • AVC-Intra
      • ProRes
      • XDCAM IMX-30/40/50
      • XDCAM HD422
      • DV
      • DNxHD
      • RED
      • AAC using Nablet
  • Storages and Files
    • Storages
      • Storages
      • Storage methods
      • Files
      • Items and storages
      • File hashing
      • Throttling storage I/O
      • Throttling transfer to and from a storage
      • Temporary storages for transcoder output
      • Storage credentials
      • Storage method URIs
      • The universal storage method
    • Automatic import
      • Import using a specific transcoder resource
      • Setting a user for jobs started as a result of an auto import rule
      • Importing with a metadata file of an external format
      • Disable automatic import rules
      • Sidecar auto import
      • Title as metadata
      • Applying file name filters to auto import rules
      • Auto import of image sequences
    • Storage rules
      • Resolving storage rules
      • Examples
    • Filenames
      • Using a tree structure for files
      • Storage name rules
      • Naming files on storage
    • Image sequences
      • Overview
      • Importing image sequences
      • Detection of image sequences
      • Sequence URIs
      • Sequence patterns
    • URI’s, URL’s, and Special Characters
      • File paths
      • API calls
  • Jobs and Task Definitions
    • Jobs
      • Creating jobs
      • Concurrency
      • Job problems
      • Job tasks
      • Custom job types
    • JavaScript tasks
      • The job object
      • Pausing job execution
      • Vidinet job execution
      • Example: Update item metadata on import
      • Example: Update item metadata on import using XML
    • Task groups
      • Creating a task group
      • Task group criteria
      • Task group priority
      • Task group concurrency limit
      • Job problems
  • Notifications
    • Resources
    • Actions
    • Triggers
    • Job filtering
      • Job types
      • Job metadata
      • Filters
  • Resources
    • Transcoders
      • Adding a transcoder
      • Using multiple transcoders
      • How transcoders perform jobs
      • Transcoder job limit
      • The transcoder’s configuration file
      • Operations overview
    • Transcoder discovery
      • Adding a transcoder directory
      • Supported URIs
    • External transcoders
      • How it works
      • Adding an external transcoder
      • Using an external transcoder
    • Thumbnail resources
      • Adding a thumbnail resource
      • Reading thumbnails
      • Thumbnail resource permissions
      • How thumbnails are saved on disk
    • Vidispine Server Agent
      • How to install VSA
      • Connecting to Vidispine
      • Adding a share
      • VSA and S3 credentials
      • Agent properties
      • Direct transfers between VSAs
      • Port forwarding service
      • Setting up VSA to use HTTPS
    • Vidinet services
      • Adding a service
      • Configuring a service
      • Import using Vidinet
      • Transcoding using Vidinet
      • Quality control using Vidinet
      • Using Vidinet services from JavaScript
      • Transcoding using AWS Elemental MediaConvert
      • Transcoding using Bitmovin
      • Analyzing using Vidinet Cognitive Services
      • Training custom models using VidiNet Cognitive Services
      • Creating a highlight reel using Nablet Shrynk
      • Using Nablet Heightscreen to crop a video into portrait mode
      • Using Interra Baton to perform quality control on your material
    • Analyzed Data Unit (ADU)
      • Example ADU
    • Callback location resources
      • Adding a callback location resource
      • Callback Document format
    • Resource Tags
      • Adding resource tags to VSA
      • Adding resource tags to storage
      • Removing resource tags
  • Timelines and sequences
    • Projects and sequences
      • Item sequences
      • Projects and project versions
      • Project and sequence import and export
    • Sequences definitions
      • SequenceDocument
  • Users, Groups, and Access control
    • Example
    • Access control for items, libraries, collections
      • Overview
      • Access levels
      • Priority
      • Revoking access
      • Operation
    • Access control for metadata fields
      • Permission levels
    • User authentication
      • Run-As option
      • Token authentication
      • Use access keys
      • Apache Shiro Integration
    • LDAP
      • User authentication
      • User and group synchronization
      • Troubleshooting
  • Multi-site
    • Multi-site
      • Site names
      • Multi site setup
      • Site rules
      • Conflicts
  • Miscellaneous Topics
    • Deletion lock
      • Adding locks
      • Lock expiration
      • Working with multiple locks
      • Lock inheritance
      • Transient metadata
      • Examples
  • Monitoring
    • StatsD
      • Filtering metrics
      • Tagged metrics
    • JMX
    • Metrics
      • Indexing
      • Job
      • Solr
      • OpenSearch
      • Storage
      • Resource
      • Agent
      • Transfer
      • Service
      • Transcoder
      • Broker
      • Cluster
    • APM
      • Setup
  • Configuration and Integration
    • Search backend
      • Solr
      • OpenSearch
    • System configuration
      • Indexing configuration
      • Metrics configuration
      • FTP pool configuration
      • Database purging
      • Default job priority
      • CORS configuration
      • Configuration properties
      • System properties
      • Bulky metadata storage
      • Advanced configuration/tweaking
    • External identifiers
      • Priority
      • Example: The UUID namespace
    • License handling
      • How it works
      • Redundancy and timeouts
    • Using JavaScript to extend operations
      • JavaScript engines
      • Common JavaScript functions
      • Debugging JavaScript
      • Interfacing with the JavaScript engine manually
      • Add generic JavaScript code
    • Archive Integration
      • Creating an archive storage
      • Amazon Glacier
      • Atempo Digital Archive Integration
      • Front Porch Diva Integration
    • S3 Event SQS Notifications
      • Prerequisites
      • Use IAM roles
      • Close restored files faster
      • Configure the storage
    • S3 Event SNS Notifications
      • Prerequisites
      • Close restored files faster
      • Configuration
    • Signiant Integration
      • General system configuration
      • Storage configuration
    • Aspera Integration
      • Source storage configuration
      • Destination storage configuration
    • Aspera FASP Integration
      • Transfer type
      • Storage configuration
    • FileCatalyst Integration
      • Transfer type
      • Storage configuration
    • MXFserver Integration
      • Set up
      • Usage
    • EVS IP Director Integration
      • Example
    • StorNext Integration
      • Storage configuration
      • StorNext Metadata
    • Cerify integration
      • Installation
      • Usage
      • Output
    • FIMS implementation
      • Codecs and formats
    • CloudConvert Integration
      • How to use
      • Source file access
      • Conversion parameters
      • CloudConvert callback
      • Enable CloudConvert using JavaScript
      • Using cloudconvert API V2
    • EIDR Integration
      • Setup
      • EIDR synchronization
      • Troubleshooting
  • Troubleshooting and obtaining information
    • Self test
      • Tests
      • Test results
      • Running the test
    • Error log report
      • Usage
      • Programmatically retrieving log files
  • Installation
    • Installing distribution-specific packages
      • Install the packages
      • Initialize the database
      • Start the services
      • Configure Vidispine
    • Quick setup
    • Service configuration
      • The vidispine service user
      • Service dependencies
      • Setting JVM options
    • Clustering
      • Quick cluster setup
    • Upgrading
      • Upgrading Vidispine
      • Upgrading to Vidispine 5.0
    • Server configuration
      • Environment variables
      • Additional settings
    • Package reference
      • Packages
      • Optional packages
      • Files
  • API Reference
    • Access controls
      • Managing access controls
      • Managing access controls in bulk
      • Default access controls
      • Viewing applied access controls
      • Access visualization
    • Audit trails
      • Examining the log
    • Collections
      • Managing collections
      • Collection content
      • Collection metadata
      • Searching for collections
      • Ordering collections
      • Folder mapped collections
    • Deletion locks
      • Manage deletion locks
      • Managing Deletion Locks
    • Configuration
      • Configuration resources
      • Indexing settings
      • Metrics settings
      • Path alias configuration
      • Job pool configuration
      • FTP pool configuration
      • Log report configuration
      • CORS configuration
      • Database purging configuration
      • Default job priority configuration
      • OAuth2 configuration
      • Bulky metadata storage configuration
      • Configuration properties
    • Export locations
      • Managing export locations
      • Export location script
    • External identifiers
      • Managing external id namespaces
      • Managing external ids
    • Groups and roles
      • Managing groups
      • Group information
      • Group-to-group relations
      • Group-to-user relations
    • Imports
      • Importing an item
      • Placeholder imports
      • Importing sidecar files
    • Import settings
      • Managing import settings
    • Items
      • Exports
      • Items
      • Retrieving item information
      • Item locks
      • Item-to-item relations
      • Item sequences
      • Shapes
      • Shape analysis
      • Shape components
      • Thumbnails
      • Transcoding
      • Item conform
      • Timeline
    • JavaScript
      • Testing scripts
      • JavaScript sessions
    • Jobs
      • Managing jobs
      • Job problem conditions
      • Job states
      • Job priority
      • Job types
      • Job metadata
    • Libraries
      • Managing libraries
      • Library settings
      • Library content
      • Listing library items in batch
    • License
      • Version and license
      • Slave management and monitoring
    • Metadata
      • Auto-projection rules
      • Bulky metadata
      • Global metadata
      • Document metadata
      • Key-value metadata
      • Metadata
      • Re-indexing metadata
      • Metadata locks
      • Metadata fields
      • Metadata field access controls
      • Metadata field groups
      • Metadata datasets
      • Metadata migrations
      • Metadata projections
      • Metadata schema
      • Subtitles
    • Miscellaneous
      • Stitching images
      • Time zone
      • Troubleshooting
      • WADL
      • Callback
      • Return the current user
    • Notifications
      • Actions
      • Triggers
      • Notifications
    • Projects and versions
      • Projects
      • Project versions
      • Version definitions
      • Assets in project version definition
      • Version definition extradata
      • Inspecting project files
      • Importing projects and sequences
      • Exporting projects and sequences
    • Quota rules
      • Managing quota rules
    • Resources
      • Resource types
      • Resources
      • Resource status
      • Resource configuration
    • Scheduling requests
      • States of scheduled requests
      • Managing scheduled requests
    • Search
      • Search items and collections
      • Search shapes
      • Search files
      • Autocompletion
      • Optimize index
    • Self tests
      • Running the test
    • Shape tags
      • Managing shape tags
      • Tags of a shape
      • Transcode preset scripts
    • Sites
      • Managing sites
    • Site rules
      • Managing site rules
    • Storages
      • Auto-import rules
      • Files
      • Storages
      • Storage groups
      • Storage name rules
      • Storage rules
    • Task definitions
      • Task definitions
      • Custom job types
      • Task definition scripts
      • Job graphs
    • Task groups
      • Task groups
      • Task group transcoders
      • Key-value metadata
    • Transfers
      • Overview
      • Managing transfers
    • Transfer log
      • Examining the log
    • Users
      • Users
      • User access keys
      • User aliases
      • User authentication tokens
    • Vidinet
      • Cost estimation
    • Vidispine logs
      • Retrieving log files
      • Log retrieval jobs
      • Upload of logs to Vidispine
    • Vidispine services
      • Vidispine services
      • Service status
      • Stack trace
    • Vidispine server agents
      • Managing VSAs
    • XML Schema
      • xmlSchema.xsd
      • common.xsd
      • transcoder.xsd
  • Release Notes
    • Prerequisites
    • Upgrade notes
      • General
      • Upgrading from 5.4 to 5.5
      • Upgrading from 5.3 to 5.4
      • Upgrading from 5.2 to 5.3
      • Upgrading from 5.1 to 5.2
      • Upgrading from 5.0 to 5.1
      • Upgrading from 4.17 to 5.0
      • Upgrading from 4.16 to 4.17
      • Upgrading from 4.15 to 4.16
      • Upgrading from 4.14 to 4.15
      • Upgrading from 4.13 to 4.14
      • Upgrading from 4.12 to 4.13
      • Upgrading from 4.11 to 4.12
      • Upgrading from 4.10 to 4.11
      • Upgrading from 4.9 to 4.10
      • Upgrading from 4.8 to 4.9
      • Upgrading from 4.7 to 4.8
      • Upgrading from 4.6 to 4.7
      • Upgrading from 4.5 to 4.6
      • Upgrading from 4.4 to 4.5
      • Upgrading from 4.3 to 4.4
      • Upgrading from 4.2 to 4.3
      • Upgrading from 4.1 to 4.2
      • Upgrading from 4.0 to 4.1
    • 22.2
      • Migration from Elasticsearch to OpenSearch
      • New features
      • Improvements
      • Bug fixes
      • Transcoder fixes
    • 22.1
      • 22.1.2
      • 22.1.1
      • 22.1
    • 21.4
      • 21.4.4
      • 21.4.3
      • 21.4.2
      • 21.4.1
      • 21.4
    • 21.3
      • 21.3.6
      • 21.3.5
      • 21.3.4
      • 21.3.3
      • 21.3.2
      • 21.3.1
      • 21.3
    • 5.7
      • 5.7.6
      • 5.7.5
      • 5.7.4
      • 5.7.3
      • 5.7.2
      • 5.7.1
      • 5.7
    • 5.6
      • 5.6.6
      • 5.6.5
      • 5.6.4
      • 5.6.3
      • 5.6.2
      • 5.6.1
      • 5.6
    • 5.5
      • 5.5.5
      • 5.5.4
      • 5.5.3
      • 5.5.2
      • 5.5.1
      • 5.5
    • 5.4
      • 5.4.5
      • 5.4.4
      • 5.4.3
      • 5.4.2
      • 5.4.1
      • 5.4
    • 5.3
      • 5.3.6
      • 5.3.5
      • 5.3.4
      • 5.3.3
      • 5.3.2
      • 5.3.1
      • 5.3
    • 5.2
      • 5.2.5
      • 5.2.4
      • 5.2.3
      • 5.2.2
      • 5.2.1
      • 5.2
    • 5.1
      • 5.1.6
      • 5.1.5
      • 5.1.4
      • 5.1.3
      • 5.1.2
      • 5.1.1
      • 5.1
    • 5.0
      • 5.0.9
      • 5.0.8
      • 5.0.7
      • 5.0.6
      • 5.0.5
      • 5.0.4
      • 5.0.3
      • 5.0.2
      • 5.0.1
      • 5.0
    • 4.17
      • 4.17.10
      • 4.17.9
      • 4.17.8
      • 4.17.7
      • 4.17.6
      • 4.17.5
      • 4.17.4
      • 4.17.3
      • 4.17.2
      • 4.17.1
      • 4.17
    • 4.16
      • 4.16.7
      • 4.16.6
      • 4.16.5
      • 4.16.4
      • 4.16.3
      • 4.16.2
      • 4.16.1
      • 4.16
    • 4.15
      • 4.15.4
      • 4.15.3
      • 4.15.2
      • 4.15.1
      • 4.15
    • 4.14
      • 4.14.6
      • 4.14.5
      • 4.14.4
      • 4.14.3
      • 4.14.2
      • 4.14.1
      • 4.14
    • 4.13
      • 4.13.4
      • 4.13.3
      • 4.13.2
      • 4.13.1
      • 4.13
    • 4.12
      • 4.12.5
      • 4.12.4
      • 4.12.3
      • 4.12.2
      • 4.12.1
      • 4.12
    • 4.11
      • 4.11.3
      • 4.11.2
      • 4.11.1
      • 4.11
    • 4.10
      • 4.10.4
      • 4.10.3
      • 4.10.2
      • 4.10.1
      • 4.10
    • 4.9
      • 4.9.3
      • 4.9.2
      • 4.9.1
      • 4.9
    • 4.8
      • 4.8.3
      • 4.8.2
      • 4.8.1
      • 4.8
    • 4.7
      • 4.7.4
      • 4.7.3
      • 4.7.2
      • 4.7.1
      • 4.7
    • 4.6
      • 4.6.5
      • 4.6.4
      • 4.6.3
      • 4.6.2
      • 4.6.1
      • 4.6
    • 4.5
      • 4.5.9
      • 4.5.8
      • 4.5.7
      • 4.5.6
      • 4.5.5
      • 4.5.4
      • 4.5.3
      • 4.5.2
      • 4.5.1
      • 4.5
    • 4.4
      • 4.4.4
      • 4.4.3
      • 4.4.2
      • 4.4.1
      • 4.4
    • 4.3
      • 4.3.8
      • 4.3.7
      • 4.3.6
      • 4.3.5
      • 4.3.4
      • 4.3.3
      • 4.3.2
      • 4.3.1
      • 4.3
    • 4.2
      • 4.2.16
      • 4.2.15
      • 4.2.14
      • 4.2.13
      • 4.2.12
      • 4.2.11
      • 4.2.10
      • 4.2.9
      • 4.2.8
      • 4.2.7
      • 4.2.6
      • 4.2.5
      • 4.2.4
      • 4.2.3
      • 4.2.2
      • 4.2.1
      • 4.2
 
Vidispine REST API
  • Docs »
  • API Reference »
  • Search

Search¶

Search for items and collections.

  • Search items and collections
  • Search shapes
  • Search files
  • Autocompletion
  • Optimize index

Search items and collections¶

Items and collections be browsed and searched with a single request. This type of search essentially has the combined set of the functionality of item search and collection search.

List all items and collections¶

GET /search¶

Browses items and collections.

Content Parameters:
 

See Retrieving item information

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

    • * - The initial cursor.
    • string-from-search - Cursor string returned from the search results.

    If set, the cursorMark / search after features from Solr/OpenSearch are used to improve the deep paging performance during a search.

    When cursor is used, the value of first will be ignored.

  • 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.
  • 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.
  • noauth-url (boolean) –
    • true Return URIs that do not need authentication.
    • false (default) Return normal URIs
  • baseURI (string) – Which base URI to use for the thumbnail URLs.
  • save (boolean) –
    • true - Returns a 303 See Other, with a Location header containing an URI to fetch the search result
    • false (default) - Returns a regular search result
Produces:
  • application/xml, application/json – SearchResultDocument
Role:

_item_search

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)

Search items and collections¶

PUT /search¶

Searches items and collections with a shared search query.

Note

This resource doesn’t support joint search, use PUT /item, PUT /search/shape or PUT /search/file for item, shape or file joint search respectively.

Content Parameters:
 

See Retrieving item information

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

    • * - The initial cursor.
    • string-from-search - Cursor string returned from the search results.

    If set, the cursorMark / search after features from Solr/OpenSearch are used to improve the deep paging performance during a search.

    When cursor is used, the value of first will be ignored.

  • 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.
  • 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.
  • 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
Accepts:
  • application/xml, application/json – ItemSearchDocument
Produces:
  • application/xml, application/json – SearchResultDocument
Role:

_item_search

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¶

PUT /search?content=metadata&field=title
Content-Type: application/xml

<ItemSearchDocument xmlns="http://xml.vidispine.com/schema/vidispine">
    <field>
        <name>title</name>
        <value>Something</value>
    </field>
</ItemSearchDocument>
<SearchResultDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <hits>3</hits>
  <entry start="-INF" end="+INF" type="Item" id="DE-42">
    <item id="DE-42" start="-INF" end="+INF">
      <metadata>
        <revision>DE-278,DE-276,DE-277</revision>
        <timespan start="-INF" end="+INF">
          <field uuid="e527b7f3-1bfa-4067-8dde-753368c09617" user="admin" timestamp="2012-03-23T10:10:42.845+01:00" change="DE-278">
            <name>title</name>
            <value uuid="38609429-67d1-4357-980c-64e7559768ff" user="admin" timestamp="2012-03-23T10:10:42.845+01:00" change="DE-278">Something</value>
          </field>
        </timespan>
      </metadata>
    </item>
    <timespan start="-INF" end="+INF"/>
  </entry>
  <entry start="-INF" end="+INF" type="Collection" id="DE-13">
    <collection>
      <id>DE-13</id>
      <metadata>
        <revision>DE-273,DE-279</revision>
        <timespan start="-INF" end="+INF">
          <field uuid="c203856a-e8e3-4d50-8287-642821941791" user="admin" timestamp="2012-03-23T10:10:57.103+01:00" change="DE-279">
            <name>title</name>
            <value uuid="f80fb9a1-1eca-479a-8b1a-11d30f93fa5d" user="admin" timestamp="2012-03-23T10:10:57.103+01:00" change="DE-279">Something</value>
          </field>
        </timespan>
      </metadata>
    </collection>
    <timespan start="-INF" end="+INF"/>
  </entry>
  <entry start="-INF" end="+INF" type="Item" id="DE-37">
    <item id="DE-37" start="-INF" end="+INF">
      <metadata>
        <revision>DE-255,DE-280,DE-256</revision>
        <timespan start="-INF" end="+INF">
          <field uuid="f1ac0198-6b8f-43a0-9caa-e8c36e80eee8" user="admin" timestamp="2012-03-23T10:11:16.849+01:00" change="DE-280">
            <name>title</name>
            <value uuid="dcd6a3bb-bf70-4cb7-8d77-e2adfe1e3b1c" user="admin" timestamp="2012-03-23T10:11:16.849+01:00" change="DE-280">Something</value>
          </field>
        </timespan>
      </metadata>
    </item>
    <timespan start="-INF" end="+INF"/>
  </entry>
</SearchResultDocument>

Search shapes¶

Search shapes¶

GET /search/shape¶
PUT /search/shape¶

Searches shapes. Using GET is identical as performing a search with an empty search document.

Query Parameters:
 
  • 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.
  • content (string) – Comma-separated list of the types of content to retrieve. One of component, metadata, essenceVersion, tag, mimeType and *.
  • methodType (string) – Return URIs from storage methods with a particular type. By default, return URLs with empty methodType.
  • storageType (string) – Only return URIs for files from storages of this type.
  • methodMetadata (string[]) – metadata used with storage method.
  • scheme (string) – URI scheme to return.
  • 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
Accepts:
  • application/xml, application/json – ShapeSearchDocument
Produces:
  • application/xml, application/json – ShapeListDocument
Role:

_item_shape_read

Search files¶

Search files¶

GET /search/file¶
PUT /search/file¶

Searches files. Using GET is identical as performing a search with an empty search document.

Note

This resource searches the same index and will produce the same results as GET /storage/(storage-id)/file. The only difference is the syntax, that is, the query parameters versus search documents. When using a search document it is also possible to perform joins.

Query Parameters:
 
  • 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.
  • methodType (string) – Return URIs from storage methods with a particular type. By default, return URLs with empty methodType.
  • storageType (string) – Only return URIs for files from storages of this type.
  • methodMetadata (string[]) – metadata used with storage method.
  • scheme (string) – URI scheme to return.
  • 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
Accepts:
  • application/xml, application/json – FileSearchDocument
Produces:
  • application/xml, application/json – FileListDocument
Role:

_file_read

Autocompletion¶

There are two ways to get autocomplete suggestions. The first way is to make a separate autocomplete request to the API, this will generate a result set spanning over all items that the user has access to. The second way is to embed the request in a search document. When performed in this way, the autocomplete suggestions will only span the matching result set.

Autocomplete text¶

Text can be autocompleted against the search index.

PUT /search/autocomplete¶

Requests suggestion matching text in all or a specific metadata field.

Status Codes:
  • 400 Bad request – A parameter was invalid.
Accepts:
  • application/xml, application/json – AutocompleteRequestDocument
Produces:
  • application/xml, application/json – AutocompleteResponseDocument
Role:

_search

Example¶

Assuming the user intends to type “original duration”. The user first starts typing “original”:

PUT /search/autocomplete
Content-Type: application/xml

<AutocompleteRequestDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <text>orig</text>
  <maximumSuggestions>3</maximumSuggestions>
</AutocompleteRequestDocument
<AutocompleteResponseDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <suggestion>original</suggestion>
  <suggestion>origin</suggestion>
  <suggestion>originated</suggestion>
</AutocompleteResponseDocument>

Then the user continues to start typing “duration”:

<AutocompleteRequestDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <text>original dur</text>
  <maximumSuggestions>3</maximumSuggestions>
</AutocompleteRequestDocument>
<AutocompleteResponseDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <suggestion>original duration</suggestion>
</AutocompleteResponseDocument>

Autocomplete on one metadata field¶

Auto-complete on one metadata field is supported. In order to make the auto-complete case insensitive, the metadata field should be set as <index>extend</index>.

Example:¶

A metadata field foo_bar with config:

<MetadataFieldDocument xmlns="http://xml.vidispine.com/schema/vidispine">
         <type>string-exact</type>
         <index>extend</index>
</MetadataFieldDocument>

and this filed contains multiple values: “Animal”, “Sky”, “Animal and Sky”, “animal and sky”

An auto-complete request with user input “animal a”:

PUT /search/autocomplete
Content-Type: application/xml

<AutocompleteRequestDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <field>foo_bar</field>
  <text>animal a</text>
</AutocompleteRequestDocument>

will give result:

<AutocompleteResponseDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <suggestion>Animal and Sky</suggestion>
  <suggestion>animal and sky</suggestion>
</AutocompleteResponseDocument>

Autocompletion as part of a search¶

To perform an autocomplete within a search, just append one or more <autocomplete> elements in the search document. The syntax is the same as for a separate autocomplete request.

Example¶

PUT /item
Content-Type: application/xml

<ItemSearchDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <field>
    <name>my_category</name>
    <value>stock_photo</value>
  </field>
  <autocomplete>
    <field>my_tag</field>
    <text>hi</text>
  </autocomplete>
</ItemSearchDocument>
<ItemListDocument xmlns="http://xml.vidispine.com/schema/vidispine">
  <hits>5</hits>
  <item id="VX-6934" start="-INF" end="+INF">
    <timespan start="-INF" end="+INF"/>
  </item>
  <item id="VX-3464" start="-INF" end="+INF">
    <timespan start="-INF" end="+INF"/>
  </item>
  <item id="VX-2658" start="-INF" end="+INF">
    <timespan start="-INF" end="+INF"/>
  </item>
  <item id="VX-7234" start="-INF" end="+INF">
    <timespan start="-INF" end="+INF"/>
  </item>
  <item id="VX-3723" start="-INF" end="+INF">
    <timespan start="-INF" end="+INF"/>
  </item>
  <autocomplete>
    <field>my_tag</field>
    <suggestion>highres</suggestion>
    <suggestion>hills</suggestion>
    <suggestion>history</suggestion>
  </autocomplete>
</ItemListDocument>

Optimize index¶

If you wish to optimize the Solr index then we recommend that this is done via this API instead of sending an optimize request to Solr directly.

Note

Solr needs twice the disk space when optimizing the index. Make sure there’s enough free space on the drive hosting the Solr index before optimizing.

Note

Solr will not accept updates while optimizing, meaning that new or updated item will not appear in the search results until the optimize operation has finished.

Optimize the search index¶

POST /search/optimize¶

Submits an optimize request to Solr.

This request can be made to block until the optimize request has completed using the blocking parameter.

Query Parameters:
 
  • blocking (boolean) –
    • true - The request will block until the Solr optimize request has finished.
    • false (default) - Optimize will be scheduled and the request will return immediately.
  • timeout (integer) – Block for maximum number of specified milliseconds. Default is 0, which means block indefinitely.
Status Codes:
  • 200 OK – If the operation finished successfully. Only if blocking=true.
  • 202 Accepted – If the operation was accepted but not yet finished.
  • 500 Internal Server Error – If an error occurs.
Role:

_administrator

Next Previous

© Copyright 2014-2022, Vidispine AB.