Please note: Deep Search is currently only available to select customers.

Deep Search Overview

Repustate's Deep Search API is a simple RESTful API. All responses are in JSON format. Pay special attention to which HTTP verb is required. Successful responses return an HTTP status code of 200. Incorrect or missing arguments will result in status code 400.

Endpoint

The API endpoint is located at https://api.repustate.com/v4

Rate Limiting

There are no limits to the number of calls you can make per minute/hour/day etc. however all accounts are subject to monthly limits according to the plan you signed up for. In the event that you exceed your monthly quota, you will receive an HTTP 429 response on all subsequent API calls.

Client Libraries

We've got client libraries to help you out. Download a Repustate client to get started.

Authentication

There is no explicit authentication mechanism. You simply include your API key in each API request.

Search /search.json
GET

Search the specified Deep Search index for matching documents. Up to 100 documents are returned in one call, but search supports pagination via a cursor request argument.

Name Notes
index required The index you'd like to query.
q required Your properly formatted Deep Search query. The query must conform to the Deep Search Query Language (DSQL) specification.
cursor If specified, results will be returned indexed in at the cursor value. Use this to paginate through your search results.
since Queries will only return documents inserted since a particular time. Format is seconds since epoch.
until Queries will only return documents inserted prior to a particular time. Format is seconds since epoch.
Name Notes
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
matches The documents that matched your search query.
total The total number of matching documents.
next_cursor To enable pagination of results, the value of next_cursor can be passed to subsequent requests to get the next page of matching documents.
prev_cursor To enable pagination of results, the value of prev_cursor can be passed to subsequent requests to get the previous page of matching documents.
{
    "status":"OK",
    "matches":[ ... ],
    "next_cursor":2132130912301
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.search(index:"my-index", query:"Person.politician.gender:M")
                    
from repustate import Client

client = Client(api_key='YOUR_API_KEY', version='v4')
client.search(index="my-index", query="Person.politician.gender:M")
                  
curl https://api.repustate.com/v4/YOUR_API_KEY/search.json?query=Person.politician.gender:M&index=my-index
                        

Add document /search.json
PUT

Add a new document to a Deep Search index. If the index doesn't exist, it will be created.

Name Notes
index required The index to which you'd like to add a new document. Index names can be any string no longer than 40 characters.
title required The title of your document
text required The body of the document you want to index.
lang The language your document is in. If left blank, English (en) is assumed.
Name Notes
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
docid The document ID for your newly added document.
{
    "status":"OK",
    "docid":"efda129281fdaecbbb10"
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.add_document(index:"my-index", title:"my title", text:"my new document", lang:"en")
                    
from repustate import Client

client = Client(api_key='YOUR_API_KEY', version='v4')
client.add_document(index="my-index", title="my title", text="my new document", lang="en")
                  
curl -X PUT -d "index=my-index&title=my title&text=my new document&lang=en" \
  https://api.repustate.com/v4/YOUR_API_KEY/search.json

Delete document /search.json
DELETE

Delete a document from your Deep Search Index

Name Notes
docId required The document ID of the document you'd like to delete.
Name Notes
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
{
    "status":"OK"
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.delete_document(docId:"23213")
                    
from repustate import Client

client = Client(api_key='YOUR_API_KEY', version='v4')
client.delete_document(docId="23213")
                  
curl https://api.repustate.com/v4/YOUR_API_KEY/search.json-X DELETE -G -d "docId=21345"
                        

Delete index /search.json
DELETE

Delete the specified Deep Search Index

Name Notes
index required The index you'd like to delete. This operation cannot be undone.
Name Notes
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
{
    "status":"OK"
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.delete_index(index:"my-index")
                    
from repustate import Client

client = Client(api_key='YOUR_API_KEY', version='v4')
client.delete_index(index="my-index")
                  
curl https://api.repustate.com/v4/YOUR_API_KEY/search.json -X DELETE -G -d "index=my-index"
                        

List search classifications /search-classifications.json
GET

List all possible classifications that Deep Search can return

This call does not take any arguments.
Name Notes
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
classifications The full list of classifications that Deep Search can identify
{
    "status":"OK",
    "classifications":["Location.country", "Location.citytown", "Location.continent", "Location.region", "Location.tourist_attraction" ...] 
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.search_classifications()
                    
from repustate import Client

client = Client(api_key='YOUR_API_KEY', version='v4')
client.search_classifications()
                  
curl https://api.repustate.com/v4/YOUR_API_KEY/search-classifications.json
                        

List search metadata /search-metadata.json
GET

For a given Deep Search classification, show all possible metadata properties that be searched against.

Name Notes
classification required The classification you want to list metadata for.
Name Notes
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
metadata A listing of all metadata for the given entities.
{
    "status":"OK",
    "metadata":["Location.country.areaKm","Location.country.population", "Location.country.GDP"]
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.metadata("Location.country")
                    
from repustate import Client

client = Client(api_key='YOUR_API_KEY', version='v4')
client.metadata("Location.country")
                  
curl https://api.repustate.com/v4/YOUR_API_KEY/search-metadata.json?classification=Location.country
                        

Similar documents /similar.json
POST

Given a block of text, returns the documents most similar semantically, ranked in order of similarity. At most, 100 documents are returned in a single request.

Name Notes
index required The index you'd like to search against for similar documents.
text required The block of text you'd like to find similar documents for.
cursor If specified, results will be returned indexed in at the cursor value. Use this to paginate through your search results.
Name Notes
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
matches The documents that are most similar to the supplied block of text, from a semantic point of view. Documents are listed in order of similarity.
total The total number of documents that Deep Search considers similar.
next_cursor When more than 100 documents are deemed to be similar, use this value for subsequent requests to fetch the next 100 documents.
{
    "status":"OK",
    "matches":[...],
    "next_cursor":912321321323
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.similar(text:"Find me documents similar to me.", index:"my-index")
                    
from repustate import Client

client = Client(api_key='YOUR_API_KEY', version='v4')
client.similar(text="Find me documents similar to me.", index="my-index")
                  
curl -d "text=Find me documents similar to me.&index=my-index" \
  https://api.repustate.com/v4/YOUR_API_KEY/similar.json

Similarity /similar.json
POST

Given two documents, return a numeric score indicating how semantically similar they are. A score closer to 0 would indicate little semantic similarity while a score closer to 1 indicates high degree of similarity.

Note that documents have to be in the same language.

Name Notes
text1 required
text2 required
Name Notes
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
similarity A decimal number between 0 and 1.
{"status":"OK", "similarity":0.8221}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.similarity(text1:"This is the first document", text2:"This is the second document")
                    
from repustate import Client

client = Client(api_key='YOUR_API_KEY', version='v4')
client.similarity(text1="This is the first document", text2="This is the second document")
                  
curl  \
  https://api.repustate.com/v4/YOUR_API_KEY/similar.json

Add Custom Entity /custom-entities.json
POST

You can add your own entities to be recognized by Deep Search. These entities will be localized to your account only and no one else can see or access them.

Name Notes
title required The name of your entity. This will be the value returned as the "full_title" attribute in any call to entities.json
body required This text describes your entity. The more relevant and longer the text, the better, as this helps Deep Search disambiguate your entity in the event that it identifies two or more similarly named entities. Keywords that accurately describe your entity should be included as part of the description.
classifications required A comma separated list of classifications you'd like to associate with your entity. The classifications must be from the list of already defined Deep Search classifications.
aliases A comma separated list of alternate names or spellings that this entity should go by. For example, if the entity was Frank Sinatra, an alias would be "Old Blue Eyes".
Name Notes
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
id The auto-generated ID of this new entity. You'll need this ID if you want to delete it after.
{
  "status":"OK",
  "id":"6552212c-808e-45f7-87a3-3135861eae65"
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.add_entity(title:"My Custom Entity", body:"This is my custom entity", themes:["custom"], classifications:["Person.custom_entity"])
                    
from repustate import Client

client = Client(api_key='YOUR_API_KEY', version='v4')
client.add_entity(title="My Custom Entity", body="This is my custom entity", themes=["custom"], classifications=["Person.custom_entity"])
                  
curl -d "title=My Custom Entity&body=This is my custom entity&themes[]=custom&classifications[]=Person.custom_entity" \
  https://api.repustate.com/v4/YOUR_API_KEY/custom-entities.json

List Custom Entities /custom-entities.json
GET

List all of the custom entities you have defined.

This call does not take any arguments.
Name Notes
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
entities A list of the entities you've created along with their auto generated ID
{
"entities":["id":"6552212c-808e-45f7-87a3-3135861eae65", "title":"My Custom Entity", "body":"My body", "themes":["sports", "arts"], "classifications":["Person.artist", "Person.pro_athlete"]]
}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.list_custom_entities()
                    
from repustate import Client

client = Client(api_key='YOUR_API_KEY', version='v4')
client.list_custom_entities()
                  
curl https://api.repustate.com/v4/YOUR_API_KEY/custom-entities.json
                        

Delete Custom Entities /custom-entities.json
DELETE

Delete a custom entity you previously created

Name Notes
id required The auto-generated ID for a given custom entity
Name Notes
status Possible values: OK, Error. If there is an error, you will get additional information about what went wrong (e.g. missing fields, incorrect API key) in two fields called `title` and `description`.
{"status":"OK"}
require "repustate"

client = Repustate.new('YOUR_API_KEY')
client.delete_custom_entiti(id:"6552212c-808e-45f7-87a3-3135861eae65")
                    
from repustate import Client

client = Client(api_key='YOUR_API_KEY', version='v4')
client.delete_custom_entity(id="6552212c-808e-45f7-87a3-3135861eae65")
                  
curl https://api.repustate.com/v4/YOUR_API_KEY/custom-entities.json-X DELETE -d "id=6552212c-808e-45f7-87a3-3135861eae65"
                        

Add Deep Search to your website

Repustate provides a very simple way to embed a search bar anywhere on your website to allow you to let your customers (or internal users) the ability to search any of your Deep Search indexes.

Step 1. The basic HTML required

At a bare minimum, you'll have to create an element (likely a div) to contain the Deep Search search bar widget as well as import the Deep Search Javascript file. Below is a minimal example of what's needed:


  <html>
    <head>
       <script type="text/javascript" src="https://path/to/deepsearch.js.min"></script>
   </head>
   <body>
       <div id="ds-container"></div>
   </body>
 </html>

Step 2. Configure the search widget

Now let's create the widget itself. This code should be placed right before the closing body tag. Remember to put your API key and your Deep Search index in place of the variable names below.


const el = document.getElementById("ds-container");
const options = {
    "pagesize":30
};
const searchbar = new DeepSearch(el, YOUR_API_KEY, YOUR_INDEX, options);
          

That's it!

This will create a fully functional Deep Search widget on your website or in your web application. To read more about customizing the behaviour of your search widget and how to do more complex actions like pagination and rendering results, read the JS SDK docs.