Vector Search API v1.0.0

Authentication

• HTTP Authentication, scheme: bearer

  {
    "qspace_id":  "SPACE-ID",
    "qlib_id": "LIBRARY-ID",
    "addr": "BLOCKCHAIN-ADDRESS",
    "tx_id" : "BLOCKCHAIN-TRANSACTION-ID"
  }

Default

Search an index

Code samples

# You can also use wget
curl -X GET /q/{qhi}/rep/search?terms=intense%20action%20scenes \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /q/{qhi}/rep/search?terms=intense%20action%20scenes HTTP/1.1

Accept: application/json

var headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: '/q/{qhi}/rep/search',
  method: 'get',
  data: '?terms=intense%20action%20scenes',
  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

fetch('/q/{qhi}/rep/search?terms=intense%20action%20scenes',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get '/q/{qhi}/rep/search',
  params: {
  'terms' => 'string'
}, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('/q/{qhi}/rep/search', params={
  'terms': 'intense action scenes'
}, headers = headers)

print r.json()

URL obj = new URL("/q/{qhi}/rep/search?terms=intense%20action%20scenes");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "/q/{qhi}/rep/search", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

 'application/json',
    'Authorization' => 'Bearer {access-token}',
    
    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','/q/{qhi}/rep/search', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

GET /q/{qhi}/rep/search

Returns search results for any valid index object on the fabric.

Parameters

Detailed descriptions

qhi: A content hash or ID.

• The hash of a finalized content object.
• A content ID. The given ID will be resolved to the latest version of that content.

select: Metadata path to the subtree to retrieve. May be specified multiple times.

remove: Metadata path of the subtree to remove from the result. May be specified multiple times.

start: Index of the first content object to retrieve. Leave empty to retrieve the first content.

limit: Integer specifying the number of contents to return.

Example responses

200 Response

{
  "pagination": {},
  "results": [
    {}
  ],
  "stats": {},
  "contents": [
    {}
  ],
  "warnings": [
    "string"
  ]
}

Responses

Response Schema

Status Code 200

Get timecoded tags

Code samples

# You can also use wget
curl -X GET /q/{qhi}/tags \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /q/{qhi}/tags HTTP/1.1

Accept: application/json

var headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: '/q/{qhi}/tags',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

fetch('/q/{qhi}/tags',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get '/q/{qhi}/tags',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('/q/{qhi}/tags', params={

}, headers = headers)

print r.json()

URL obj = new URL("/q/{qhi}/tags");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "/q/{qhi}/tags", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

 'application/json',
    'Authorization' => 'Bearer {access-token}',
    
    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','/q/{qhi}/tags', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

GET /q/{qhi}/tags

Returns the timecoded tags for a given content object mezzanine. Typically these are generated by the ML tagger or Evie video editor.

Parameters

Detailed descriptions

qhi: A content hash or ID.

• The hash of a finalized content object.
• A content ID. The given ID will be resolved to the latest version of that content.

start_time: Start time in milliseconds. If not specified, the start time will be set to 0.

end_time: End time in milliseconds. If not specified, the end time will be set to the end of the content.

padding: Pad the start/end time by this amount in milliseconds.

include_tracks: Include only these tracks in the result. If not specified, all tracks will be included.

Example responses

200 Response

{}

Responses

Response Schema

Stage content objects for indexing

Code samples

# You can also use wget
curl -X POST /q/{qwtoken}/update_site \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST /q/{qwtoken}/update_site HTTP/1.1

Accept: application/json

var headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: '/q/{qwtoken}/update_site',
  method: 'post',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

fetch('/q/{qwtoken}/update_site',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post '/q/{qwtoken}/update_site',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('/q/{qwtoken}/update_site', params={

}, headers = headers)

print r.json()

URL obj = new URL("/q/{qwtoken}/update_site");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "/q/{qwtoken}/update_site", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

 'application/json',
    'Authorization' => 'Bearer {access-token}',
    
    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','/q/{qwtoken}/update_site', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

POST /q/{qwtoken}/update_site

Accepts a write token against a "site" object which is an object responsible for storing content objects for indexing.

Note: The caller is responsible for finalizing the write token when the call is complete.

WARNING: The site object can be the same as the index object. But if this is the case the caller must ensure this token is finalized before invoking the crawl endpoint.

Parameters

Detailed descriptions

item_subpath: Determines the root of the content object metadata to crawl which will be the same for all contents in the site. Defaults to "meta" which indicates starting the crawl from the metadata root.

Example responses

200 Response

{
  "message": "string",
  "failed": [
    "qid1",
    "qid2"
  ]
}

Responses

Response Schema

Status Code 200

Build index

Code samples

# You can also use wget
curl -X POST /q/{qwtoken}/crawl \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST /q/{qwtoken}/crawl HTTP/1.1

Accept: application/json

var headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: '/q/{qwtoken}/crawl',
  method: 'post',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

fetch('/q/{qwtoken}/crawl',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post '/q/{qwtoken}/crawl',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('/q/{qwtoken}/crawl', params={

}, headers = headers)

print r.json()

URL obj = new URL("/q/{qwtoken}/crawl");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "/q/{qwtoken}/crawl", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

 'application/json',
    'Authorization' => 'Bearer {access-token}',
    
    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','/q/{qwtoken}/crawl', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

POST /q/{qwtoken}/crawl

This endpoint is a wrapper for the fabric-search crawl. It takes a write token against an index object. It will start the crawl LRO on a search compatibile fabric node, and callers can check the lro status via GET /q/{qhi}/crawl_status. Callers are responsible for finalizing the write token when the crawl is complete.

Note: This call creates a traditional keyword index not a vectorized index. To upgrade to a vector index, use the POST /q/{qhi}/search_update endpoint.

Parameters

Example responses

200 Response

{
  "message": "string",
  "lro_handle": "string"
}

Responses

Response Schema

Status Code 200

Check the status of a crawl job.

Code samples

# You can also use wget
curl -X GET /q/{qwtoken}/crawl_status \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

GET /q/{qwtoken}/crawl_status HTTP/1.1

Accept: application/json

var headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: '/q/{qwtoken}/crawl_status',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

fetch('/q/{qwtoken}/crawl_status',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get '/q/{qwtoken}/crawl_status',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('/q/{qwtoken}/crawl_status', params={

}, headers = headers)

print r.json()

URL obj = new URL("/q/{qwtoken}/crawl_status");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "/q/{qwtoken}/crawl_status", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

 'application/json',
    'Authorization' => 'Bearer {access-token}',
    
    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','/q/{qwtoken}/crawl_status', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

GET /q/{qwtoken}/crawl_status

Parameters

Example responses

200 Response

{}

Responses

Response Schema

Upgrade index to vectorized version

Code samples

# You can also use wget
curl -X POST /q/{qhi}/search_update \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

POST /q/{qhi}/search_update HTTP/1.1

Accept: application/json

var headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: '/q/{qhi}/search_update',
  method: 'post',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Accept':'application/json',
  'Authorization':'Bearer {access-token}'

};

fetch('/q/{qhi}/search_update',
{
  method: 'POST',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Accept' => 'application/json',
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.post '/q/{qhi}/search_update',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer {access-token}'
}

r = requests.post('/q/{qhi}/search_update', params={

}, headers = headers)

print r.json()

URL obj = new URL("/q/{qhi}/search_update");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Accept": []string{"application/json"},
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("POST", "/q/{qhi}/search_update", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

 'application/json',
    'Authorization' => 'Bearer {access-token}',
    
    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('POST','/q/{qhi}/search_update', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

POST /q/{qhi}/search_update

Build a vectorized version of a given index object asynchronously. Callers can check status via GET /q/{qhi}/update_status.

The index is not committed to the fabric and exists only within the context of this service.

The update involves chunking the metadata and building a single vector embedding per chunk. This can be a length operation depending on the size of the metadata. A vector index will be built against these vectors for efficient semantic retrieval.

Note: The provided content id must be previously crawled.

Note: Vectorization only affects the ranking of the results not the content itself or the API for searching.

WARNING: Vectorization will make search queries significantly slower. If this is undesirable the caller can use the "text" query parameter in the search endpoint to force keyword search.

Parameters

Detailed descriptions

qhi: A content hash or ID.

• The hash of a finalized content object.
• A content ID. The given ID will be resolved to the latest version of that content.

Example responses

200 Response

{
  "success": true
}

Responses

Response Schema

Status Code 200

Check vector indexing status

Code samples

# You can also use wget
curl -X GET /q/{qhi}/update_status \
  -H 'Authorization: Bearer {access-token}'

GET /q/{qhi}/update_status HTTP/1.1

var headers = {
  'Authorization':'Bearer {access-token}'

};

$.ajax({
  url: '/q/{qhi}/update_status',
  method: 'get',

  headers: headers,
  success: function(data) {
    console.log(JSON.stringify(data));
  }
})

const fetch = require('node-fetch');

const headers = {
  'Authorization':'Bearer {access-token}'

};

fetch('/q/{qhi}/update_status',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

require 'rest-client'
require 'json'

headers = {
  'Authorization' => 'Bearer {access-token}'
}

result = RestClient.get '/q/{qhi}/update_status',
  params: {
  }, headers: headers

p JSON.parse(result)

import requests
headers = {
  'Authorization': 'Bearer {access-token}'
}

r = requests.get('/q/{qhi}/update_status', params={

}, headers = headers)

print r.json()

URL obj = new URL("/q/{qhi}/update_status");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("GET");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();
System.out.println(response.toString());

package main

import (
       "bytes"
       "net/http"
)

func main() {

    headers := map[string][]string{
        "Authorization": []string{"Bearer {access-token}"},
        
    }

    data := bytes.NewBuffer([]byte{jsonReq})
    req, err := http.NewRequest("GET", "/q/{qhi}/update_status", data)
    req.Header = headers

    client := &http.Client{}
    resp, err := client.Do(req)
    // ...
}

 'Bearer {access-token}',
    
    );

$client = new \GuzzleHttp\Client();

// Define array of request body.
$request_body = array();

try {
    $response = $client->request('GET','/q/{qhi}/update_status', array(
        'headers' => $headers,
        'json' => $request_body,
       )
    );
    print_r($response->getBody()->getContents());
 }
 catch (\GuzzleHttp\Exception\BadResponseException $e) {
    // handle exception or api errors.
    print_r($e->getMessage());
 }

 // ...

GET /q/{qhi}/update_status

This endpoint will return the status of a search update job referenced by it's content object id or content hash.

Parameters

Detailed descriptions

qhi: A content hash or ID.

• The hash of a finalized content object.
• A content ID. The given ID will be resolved to the latest version of that content.

Responses

Schemas

Errors

[
  {
    "op": "string",
    "kind": "string",
    "cause": {},
    "stacktrace": [
      "string"
    ],
    "property1": {},
    "property2": {}
  }
]

Properties

Error

{
  "op": "string",
  "kind": "string",
  "cause": {},
  "stacktrace": [
    "string"
  ],
  "property1": {},
  "property2": {}
}

Properties

ErrorRes

{
  "errors": [
    {
      "op": "authentication",
      "kind": "invalid",
      "cause": "authorization header missing",
      "stacktrace": "..."
    }
  ]
}

Properties