DEEP-SEARCH-API

Search

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.

Request
path Parameters
apikey
required
string

Valid API key for your account

query Parameters
index
required
string

The index you'd like to query.

q
required
string

Your properly formatted Deep Search query. The query must conform to the Deep Search Query Language (DSQL) specification.

page
integer

Indicates which page to return results from. The offset is effective pagesize * page

pagesize
integer

The number of documents to return per request.

Responses
200

OK

400

error

get/{apikey}/search.json
Request samples
curl https://api.repustate.com/v4/{apikey}/search.json?q=Person.politician.gender:M&index=my-index
Response samples
application/json
{
  • "matches": [
    ],
  • "next": 0,
  • "prev": 0,
  • "status": "OK",
  • "total": 1
}

Add document

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

Request
path Parameters
apikey
required
string

Valid API key for your account

Request Body schema: multipart/form-data
otherid
string

The custom id for this document

url
string

The URL for this document

index
required
string <= 40 characters

The index to which you'd like to add a new document. Index names can be any string no longer than 40 characters.

title
string

The title of your document

text
required
string

The body of the document you want to index.

store
boolean

Indicated whether or not to store the text in the backend after processing. Defaults to true. Supply '0' to disable storing

lang
string

The language your document is in. If left blank, English (en) is assumed.

Responses
200

OK

put/{apikey}/search.json
Request samples
curl -X PUT -d "index=my-index&title=my title&text=my new document with George Bush Sr. as the male politician&lang=en" \
https://api.repustate.com/v4/{apikey}/search.json
        
Response samples
application/json
{
  • "entities": {
    },
  • "lang": "en",
  • "sentiment": "neu",
  • "status": "OK",
  • "themes": "politics"
}

Delete document OR Index

Delete a document from your Deep Search Index

Request
path Parameters
apikey
required
string

Valid API key for your account

query Parameters
id
required
string

The document ID of the document you'd like to delete. It cannot be used in conjuction with index parameter

index
required
string

The index you'd like to delete. This operation cannot be undone. It cannot be used in conjuction with id parameter

Responses
200

OK

delete/{apikey}/search.json
Request samples
curl https://api.repustate.com/v4/{apikey}/search.json -X DELETE -G -d "id=21345"
Response samples
application/json
{
  • "status": "OK"
}

List search classifications

List all possible classifications that Deep Search can return

Request
path Parameters
apikey
required
string

Valid API key for your account

Responses
200

OK

get/{apikey}/search-classifications.json
Request samples
curl https://api.repustate.com/v4/{apikey}/search-classifications.json
Response samples
application/json
{
  • "status": "OK",
  • "classifications": [
    ]
}

List search metadata

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

Request
path Parameters
apikey
required
string

Valid API key for your account

query Parameters
classification
required
string

The classification you want to list metadata for.

Responses
200

OK

get/{apikey}/search-metadata.json
Request samples
curl https://api.repustate.com/v4/{apikey}/search-metadata.json?classification=Location.country
Response samples
application/json
{
  • "status": "OK",
  • "metadata": [
    ]
}

List custom entities

List all of the custom entities you have defined.

Request
path Parameters
apikey
required
string

Valid API key for your account

query Parameters
lang
string

The language model for which you'd like to list the custom entities you've added. Default value is English (en)

Responses
200

OK

get/{apikey}/custom-entities.json
Request samples
curl https://api.repustate.com/v4/{apikey}/custom-entities.json
Response samples
application/json
{
  • "entities": [
    ],
  • "status": "OK"
}

Add custom entity

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.

Request
path Parameters
apikey
required
string

Valid API key for your account

Request Body schema: multipart/form-data
title
required
string

The canonical name for your new entity

lang
required
string

The language model to add this new entity to

classifications
required
Array of strings

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.

Responses
200

OK

put/{apikey}/custom-entities.json
Request samples
curl -d "title=My Custom Entity&body=This is my custom entity&classifications[]=Person.politician" \
https://api.repustate.com/v4/{apikey}/custom-entities.json
Response samples
application/json
{
  • "status": "OK"
}

Delete custom entity

Deletes a custom entity you previously added.

Request
path Parameters
apikey
required
string

Valid API key for your account

query Parameters
lang
string

The language model this entity should be removed from. Default value is English (en)

title
required
string

The title of the entity you previously added and now wish to delete

Responses
200

OK

delete/{apikey}/custom-entities.json
Request samples
curl https://api.repustate.com/v4/{apikey}/custom-entities.json -X DELETE -d "title=My Custom Entity"
Response samples
application/json
{
  • "status": "OK"
}

List custom aliases

List all of the aliases defined for a custom entity you previously added

Request
path Parameters
apikey
required
string

Valid API key for your account

query Parameters
title
string

The title of the entity whose aliases you want to list

lang
string

The language model whose entities you wish to list

Responses
200

OK

get/{apikey}/custom-aliases.json
Request samples
curl https://api.repustate.com/v4/{apikey}/custom-aliases.json?title=My+Custom+Entity&lang=en
Response samples
application/json
{
  • "entities": [
    ],
  • "status": "OK"
}

Add custom alias

Add an alias to a previously added entity. This could be their Twitter handle, a translation in another language etc.

Request
path Parameters
apikey
required
string

Valid API key for your account

Request Body schema: multipart/form-data
title
required
string

The name of your entity. It must already exist for the given language model

alias
required
string

The alias you want to add as another way of referring to this entity

lang
required
string

The language model to add this alias to

Responses
200

OK

put/{apikey}/custom-aliases.json
Request samples
curl -d "title=My Entity&alias=Alias 1&lang=en"
https://api.repustate.com/v4/{apikey}/custom-aliases.json
Response samples
application/json
{
  • "status": "OK"
}

Delete custom alias

Deletes a custom alias from one of your custom entities

Request
path Parameters
apikey
required
string

Valid API key for your account

query Parameters
alias
string

The alias you'd like to remove. It will be removed from all language models it appears in

lang
string

The language model to remove the alias from

Responses
200

OK

delete/{apikey}/custom-aliases.json
Request samples
curl https://api.repustate.com/v4/{apikey}/custom-aliases.json -X DELETE -d "alias=My Alias&title=My Entity"
Response samples
application/json
{
  • "status": "OK"
}