Sajari API (v4beta1)

Download OpenAPI specification:Download

Sajari is a smart, highly-configurable, real-time search service that enables thousands of businesses worldwide to provide amazing search experiences on their websites, stores, and applications.

Authentication

BasicAuth

The Sajari API uses API keys to authenticate requests.

You should provide either your account's API key or your collection's API key. The type of key you provide depends on the required level of access for the request you are making. To administer your account (e.g. create and delete collections) you should provide an account key. For most other requests (e.g. query collection) you should provide a collection key.

Your API keys carry many privileges, so be sure to keep them secure. Do not share your API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key ID as the basic auth username value. Provide your API key secret as the basic auth password value.

$ curl https://api-gateway.sajari.com -u <key_id>:<key_secret>

You can find your account's API keys in the Sajari Console account credentials page. You can find your collection's API keys in the Sajari Console collection credentials page.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Security Scheme Type HTTP
HTTP Authorization Scheme basic

Collections

Collections store the records that you want to search through.

They also contain the configuration associated with your data including pipelines, rules, synonyms, authorized domains and analytics. Each collection has an associated schema that designates field names, field types, and whether a field's data is indexed for text search.

Create a collection for every new set of related records that you want to search through.

List collections

Retrieve a list of collections in the account.

Authorizations:
query Parameters
page_size
integer <int32>

The maximum number of collections to return. The service may return fewer than this value.

If unspecified, at most 50 collections are returned.

The maximum value is 100; values above 100 are coerced to 100.

page_token
string

A page token, received from a previous ListCollections call.

Provide this to retrieve the subsequent page.

When paginating, all other parameters provided to ListCollections must match the call that provided the page token.

Responses

200

A successful response.

default

An unexpected error response

get/v4beta1/collections
https://api-gateway.sajari.com/v4beta1/collections

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "collections":
    [
    ],
  • "next_page_token": "string"
}

Create collection

Create an empty collection.

Before records can be added to a collection, the schema and pipelines for the collection have to be set up. Consider setting up new collections via the Sajari Console, which handles the creation of the schema and pipelines for you.

Authorizations:
query Parameters
collection_id
required
string

The ID to use for the collection.

This must start with an alphanumeric character followed by one or more alphanumeric or - characters. Strictly speaking, it must match the regular expression: ^[A-Za-z][A-Za-z0-9\-]*$.

Request Body schema: application/json

Details of the collection to create.

display_name
required
string

The collection's display name. You can change this at any time.

Responses

200

A successful response.

400

Returned when the request contains violations for one or more fields.

409

Returned when the collection already exists.

default

An unexpected error response

post/v4beta1/collections
https://api-gateway.sajari.com/v4beta1/collections

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "display_name": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "account_id": "string",
  • "create_time": "2020-10-12T05:48:01Z",
  • "display_name": "string"
}

Get collection

Retrieve the details of a collection.

Authorizations:
path Parameters
collection_id
required
string

The collection to retrieve, e.g. my-collection.

Responses

200

A successful response.

default

An unexpected error response

get/v4beta1/collections/{collection_id}
https://api-gateway.sajari.com/v4beta1/collections/{collection_id}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "account_id": "string",
  • "create_time": "2020-10-12T05:48:01Z",
  • "display_name": "string"
}

Delete collection

Delete a collection and all of its associated data.

Note: this operation cannot be reversed.

Authorizations:
path Parameters
collection_id
required
string

The collection to delete, e.g. my-collection.

Responses

200

A successful response.

404

Returned when the collection was not found.

default

An unexpected error response

delete/v4beta1/collections/{collection_id}
https://api-gateway.sajari.com/v4beta1/collections/{collection_id}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{ }

Query collection

Query the collection to search for records.

The following example demonstrates how to run a simple search for a particular string:

{
  "variables": { "q": "search terms" }
}

For more information:

Authorizations:
path Parameters
collection_id
required
string

The collection to query, e.g. my-collection.

Request Body schema: application/json
pipeline
object (v4beta1QueryCollectionRequestPipeline)

The pipeline to use when querying the collection.

If not provided the default query pipeline is used.

variables
required
object

The initial values for the variables the pipeline operates on and transforms throughout its steps.

A typical variable is q which is the query the user entered, for example:

{ "q": "search terms" }
tracking
object (v2Tracking)

Responses

200

A successful response.

default

An unexpected error response

post/v4beta1/collections/{collection_id}:queryCollection
https://api-gateway.sajari.com/v4beta1/collections/{collection_id}:queryCollection

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "pipeline":
    {
    },
  • "variables": { },
  • "tracking":
    {
    }
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "pipeline":
    {
    },
  • "variables": { },
  • "query_results":
    {
    },
  • "tokens":
    [
    ]
}

Pipelines

In Sajari, you configure your search algorithm using pipelines.

Pipelines are easily configurable YAML-based scripts that define a series of steps that are executed sequentially when indexing a record, using a record pipeline, or performing a query, using a query pipeline.

Generate pipelines

Generate basic record, query and autocomplete pipeline templates. Use these templates as a starting point for your collection's pipelines.

This call returns a set of pipelines that you can pass directly to the create pipeline call.

The generated templates can be returned in JSON, the default, or YAML. To return the generated pipelines in YAML, set the request's Accept header to application/yaml. The three pipelines in the YAML response are separated by three dashes (---).

Authorizations:
path Parameters
collection_id
required
string

The collection, e.g. my-collection.

Request Body schema: application/json
searchable_fields
required
Array of strings

Prioritized list of fields to search.

query_training_fields
Array of strings

List of fields to train query suggestions from.

Responses

200

A successful response.

default

An unexpected error response

post/v4beta1/collections/{collection_id}:generatePipelines
https://api-gateway.sajari.com/v4beta1/collections/{collection_id}:generatePipelines

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "searchable_fields":
    [
    ],
  • "query_training_fields":
    [
    ]
}