Searchify API

The API defines methods to manage indexes (create and delete them), operate on them (add and delete documents, functions, etc), perform searches, etc.

All calls should be made to your specific private API url (which you'll find in your account's dashboard).

Every call will report its success via the HTTP status code returned. If the status code is 4xx or 5xx then the response body may contain a plain error message providing further details. If a 2xx code is returned the body will either be a JSON-serialized object or it'll be empty depending on the call.


Index Management

Before using an index you need to create an index and assign it a name. This name (NOT its code) has to be provided at creation time, and is used to reference that index in all other API calls.

HTTP Request / Description HTTP Response codes / body
GET /v1/indexes
Retrieves the metadata of every index in this account.
200 OK
The response body will contain a JSON map.
Each key will be an index name, and its value, the index metadata. More details...
GET /v1/indexes/name
Retrieves metadata for the index name.
200 OK
The response body will contain a JSON map with metadata for the index. More details...
404 No index existed for the given name
The response body will be empty.
PUT /v1/indexes/name
Creates or updates an index with the given name.
It cannot contain forward slashes "/".

The request body can contain a JSON object with:
  • "public_search": a boolean indicating
    whether public API is enable
201 An index has been created
The response body will contain a JSON map with metadata for the index. More details...
204 An index already existed for that name
If body was sent, the index will be modified according to the options sent.
The response body will be empty.
409 Too many indexes for this account
A descriptive error message will be found in the body.
DELETE /v1/indexes/name
Removes the index name from the account.
200 OK
The response body will be empty.
204 No index existed for that name
The response body will be empty.

Indexing

Documents can be added, updated and deleted from the index. An identifier must be provided for each document. It can be your internal identifier for that document.

This identifier will be used in the search results to reference the matching documents. Every field defined in the indexed document will be searchable. The indexed fields can be fetched or snippeted along with the search results.

HTTP Request / Description HTTP Response codes / body
PUT /v1/indexes/name/docs
Adds a document to the index name.

The request body should contain a JSON object with:
  • "docid": your document identifier
    A non-empty String no longer than 1024 bytes
  • "fields": a map from field name to field value.
    The sum of the length of each field value MUST not be greater than 100kbytes
And optionally:
  • "variables": a map from the var number to float
  • "categories": a map from the category name to its value
200 OK - Document indexed
The response body will be empty.
400 Invalid or missing argument
A descriptive error message will be found in the body.
404 No index existed for the given name
A descriptive error message will be found in the body.
409 The index was initializing
Until the value for "started" in the metadata is true attempts to add a document will fail.
503 Service Unavailable
A descriptive error message will be found in the body.
PUT /v1/indexes/name/docs
Adds a batch of documents to the index name.

The request body should contain a JSON list where each element should have the following attributes:
  • "docid": your document identifier
    A non-empty string no longer than 1024 bytes
  • "fields": a map from field name to field value.
    The sum of the length of each field value MUST not be greater than 100kbytes
And optionally:
  • "variables": a map from the var number to float
  • "categories": a map from the category name to its value
200 OK - Batch processed
The response body will be a JSON list where each element will have the following attributes:
  • "added": a boolean indicating whether the document in this position was successfully indexed
  • "error": a message detailing the reasons why a document was not successfully indexed
400 Invalid or missing argument
A descriptive error message will be found in the body.
If any of the documents in the list was malformed, this response will be given and no document will be indexed.
404 No index existed for the given name
A descriptive error message will be found in the body.
409 The index was initializing
Until the value for "started" in the metadata is true attempts to add a document will fail.
503 Service Unavailable
A descriptive error message will be found in the body.
DELETE /v1/indexes/name/docs
Removes a document from the index name.

The request body should contain a JSON object with:
  • "docid": the document identifier
For clients that do not support body in DELETE
requests the docid can be sent in the querystring
200 OK - Document deleted
The response body will be empty.
400 Invalid or missing argument
A descriptive error message will be found in the body.
404 No index existed for the given name
A descriptive error message will be found in the body.
409 The index was initializing
Until the value for "started" in the metadata is true attempts to delete a document will fail.
503 Service Unavailable
A descriptive error message will be found in the body.
DELETE /v1/indexes/name/docs
Removes a bulk of documents from the index name.

The request body should contain a JSON List where each element should have the following attributes:
  • "docid": the document identifier
For clients that do not support body in DELETE
requests the docid can be sent in the querystring one time per document.
200 OK - Bulk delete processed
The response body will be a JSON list where each element will have the following attributes:
  • "deleted": a boolean indicating whether the document in this position was successfully deleted
  • "error": a message detailing the reasons why a document was not successfully deleted
400 Invalid or missing argument
A descriptive error message will be found in the body.
404 No index existed for the given name
A descriptive error message will be found in the body.
409 The index was initializing
Until the value for "started" in the metadata is true attempts to delete a document will fail.
503 Service Unavailable
A descriptive error message will be found in the body.

Scoring variables

Documents can have numeric variables attached to them. These variables can be used in scoring functions for sorting search results. Variables can be updated rapidly; these updates don't count towards your indexing limits.

HTTP Request / Description HTTP Response codes / body
PUT /v1/indexes/name/docs/variables
Update the variables of a document in index name.

The request body should contain a JSON object with:
  • "docid": your document identifier
  • "variables": a map from the var number to float
200 OK - Variables indexed
The response body will be empty.
400 Invalid or missing argument
A descriptive error message will be found in the body.
404 No index existed for the given name
A descriptive error message will be found in the body.
409 The index was initializing
Until the value for "started" in the metadata is true attempts to update variables will fail.
503 Service Unavailable
A descriptive error message will be found in the body.

Categories

Documents already added can be categorized. Categories are a way to partition your index for different dimensions. For instance, you may want to have your documents grouped by type (cds, books), price range (0-99, 100-199), manufacturer, author, or any dimension in which your documents have meaning. For every category (the dimension) every document can have at most one value.

These categories can be used later to filter your query (e.g.: only return books that cost between 0 and 100 dollars) or to facet the results of a query (i.e. showing the user how many documents, for each category and category value, match the query)

HTTP Request / Description HTTP Response codes / body
PUT /v1/indexes/name/docs/categories
Update the categories of a document in index name.

The request body should contain a JSON object with:
  • "docid": your document identifier
  • "categories": a map from the categories' names
    to the values for this document
200 OK - Categories indexed
The response body will be empty.
400 Invalid or missing argument
A descriptive error message will be found in the body.
404 No index existed for the given name
A descriptive error message will be found in the body.
409 The index was initializing
Until the value for "started" in the metadata is true attempts to update categories will fail.
503 Service Unavailable
A descriptive error message will be found in the body.

Scoring functions

Scoring functions can be defined through the API. These functions can later be used when searching the index to provide specific orderings for the results. They can use the variables defined in the document as well as some special variables such as the document's age and the textual relevance of the match. You can find more detail in the function definition syntax page.

Geolocation can be used to prioritize documents closer to (or further from) the user's location. Check the distance functions for this.

HTTP Request / Description HTTP Response codes / body
GET /v1/indexes/name/functions
Retrieves all the functions defined for the index name.
200 OK
The response body will contain a JSON map from the function number to its definition.
404 No index existed for the given name
A descriptive error message will be found in the body.
409 The index was initializing
This will happen until the value for "started" in the metadata is true.
PUT /v1/indexes/name/functions/num
Defines the function number num for the index name.

The request body should contain a JSON object with:
  • "definition": the formula that defines the function
200 OK - Function saved
The response body will be empty.
400 Invalid or missing argument
A descriptive error message will be found in the body.
404 No index existed for the given name
A descriptive error message will be found in the body.
409 The index was initializing
This will happen until the value for "started" in the metadata is true.
DELETE /v1/indexes/name/functions/num
Removes the function num from the index name.
200 OK - Function deleted
The response body will be empty.
400 Invalid or missing argument
A descriptive error message will be found in the body.
404 No index existed for the given name
A descriptive error message will be found in the body.
409 The index was initializing
This will happen until the value for "started" in the metadata is true.
503 Service Unavailable
A descriptive error message will be found in the body.

Searching

A query must be provided to search an index. Optional parameters include: start and length (for results paging), a scoring function (for results ordering), and a list of fetch and snippet fields (for getting stored data).

Search results will contain the document identifiers provided at indexing time. If fetch and snippet fields were specified, the field's content or a snippet of the content can be returned along with the identifiers.

HTTP Request / Description HTTP Response codes / body
GET /v1/indexes/name/search
Performs a search on the index name.

The querystring should contain:
  • "q": the query to be performed
And optionally:
  • "start": for paging, the first position to return
  • "len": how many results to return (default: 10)
  • "function": the number of the scoring function to use (default: 0)
  • "fetch": comma-separated list of fields to fetch. '*' returns all present fields for each document1
  • "fetch_variables": 'true' returns all variables for each document as variable_<N> (unset vars return 0)
  • "fetch_categories": 'true' returns all categories for each document as category_<NAME>
  • "snippet": comma-separated list of fields to snippet 1
  • "var<N>": value of the query variable <N> 2
  • "category_filters": a json map from category name
    to a list of the admitted values for those categories 3
  • "filter_docvar<N>": comma-separated list of
    ranges to filter the values of variable <N>. Each range is
    expressed as BOTTOM:TOP, where any of both limits can
    be replaced by an * symbol to indicate it should be ignored
  • "filter_function<N>": comma-separated list of
    ranges to filter the values of function <N>. Each range is
    expressed as BOTTOM:TOP, where any of both limits can
    be replaced by an * symbol to indicate it should be ignored
200 OK
The response body will contain a JSON map with these fields:
  • "matches": the total number of matches for the query
  • "facets": a map from category name to a values count map
  • "results": a list of objects with the "docid" field
    • query_relevance_score: query specific document relevance score
    • variable_<N>: variable value, from 0 to N
    • category_<NAME>: category value for the NAME document category / facet
  • "search_time": the time it took to search in seconds
400 Invalid or missing argument
A descriptive error message will be found in the body.
404 No index existed for the given name
A descriptive error message will be found in the body.
409 The index was initializing
This will happen until the value for "started" in the metadata is true.
503 Service Unavailable
A descriptive error message will be found in the body.
DELETE /v1/indexes/name/search
Performs a search on the index name.

The querystring should contain:
  • "q": the query to be performed
And optionally:
  • "start": the first result to delete
  • "function": the number of the scoring function to use (default: 0) (only relevant if 'start' is being used)
  • "var<N>": value of the query variable <N> 2 (only relevant if 'start' is being used)
  • "category_filters": a json map from category name
    to a list of the admitted values for those categories 3
  • "filter_docvar<N>": comma-separated list of
    ranges to filter the values of variable <N>. Each range is
    expressed as BOTTOM:TOP, where any of both limits can
    be replaced by an * symbol to indicate it should be ignored
  • "filter_function<N>": comma-separated list of
    ranges to filter the values of function <N>. Each range is
    expressed as BOTTOM:TOP, where any of both limits can
    be replaced by an * symbol to indicate it should be ignored
200 OK
The response body will be empty.
400 Invalid or missing argument
A descriptive error message will be found in the body.
404 No index existed for the given name
A descriptive error message will be found in the body.
409 The index was initializing
This will happen until the value for "started" in the metadata is true.
503 Service Unavailable
A descriptive error message will be found in the body.

Index metadata

Some methods will return metadata for an index. This metadata will be in the form of a JSON object and will include the following fields:

Field name Content
started
boolean true / false
A boolean value representing whether the given index has started.
False usually means that the index has been recently it created and isn't available yet.
code
string alphanumeric
A string with an alphanumeric code that uniquely identifies the index under the given name.
If an index is deleted and a new one is created with the same name, it will have a different code.
creation_time
string ISO 8601 formatted date format
A string with the time when this index was created formatted according to the ISO 8601 format.
For example: 2010-01-01T12:00:00
size
integer
An integer with the size in documents of this index. The size is not updated in real-time so the value may be up to a minute old.
public_search
boolean true / false
A boolean value indicating whether public search API is enabled.

Autocomplete

JSON data source to work with Indextank-jQuery Autocomplete.

Additional support for JSONP is provided.

HTTP Request / Description HTTP Response codes / body
GET /v1/indexes/name/autocomplete
Performs a search on the index name.

The querystring parameters should contain:
  • "query": the query to be performed
And optionally:
  • "field": the field to take suggestions from. By default,
    'text' field will be chosen.
  • "callback": the callback JS function on the client (enables JSONP),
    if callback is present response will be JSONP,
    if no callback is present, response will be a JSON map
200 OK
The response body will be JSONP or a JSON map with these fields:
  • "suggestions": JSON array with query matches
  • "query": requested query parameter (may be normalized)
409 The index was initializing
This will happen until the value for "started" in the metadata is true.
400 Invalid or missing argument
A descriptive error message will be found in the body
404 No index existed for the given name
A descriptive error message will be found in the body