Sajari API (v4)

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.

401

Returned when the request does not have valid authentication credentials.

403

Returned when the user does not have permission to access the resource.

404

Returned when the resource does not exist.

500

Returned when the API encounters an internal error.

default

An unexpected error response

get/v4/collections
https://api-gateway.sajari.com/v4/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.

authorized_query_domains
Array of strings

The list of authorized query domains for the collection.

Client-side / browser requests to the QueryCollection call can be made by any authorized query domain or any of its subdomains. This allows your interface to make search requests without having to provide an API key in the client-side request.

Responses

200

A successful response.

400

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

401

Returned when the request does not have valid authentication credentials.

403

Returned when the user does not have permission to access the resource.

404

Returned when the resource does not exist.

409

Returned when the collection already exists.

500

Returned when the API encounters an internal error.

default

An unexpected error response

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

Request samples

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "account_id": "string",
  • "create_time": "2021-01-05T05:33:18Z",
  • "display_name": "string",
  • "authorized_query_domains":
    [
    ]
}

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.

401

Returned when the request does not have valid authentication credentials.

403

Returned when the user does not have permission to access the resource.

404

Returned when the resource does not exist.

500

Returned when the API encounters an internal error.

default

An unexpected error response

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "account_id": "string",
  • "create_time": "2021-01-05T05:33:18Z",
  • "display_name": "string",
  • "authorized_query_domains":
    [
    ]
}

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.

401

Returned when the request does not have valid authentication credentials.

403

Returned when the user does not have permission to access the resource.

404

Returned when the collection was not found.

500

Returned when the API encounters an internal error.

default

An unexpected error response

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

Response samples

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

Update collection

Update the details of a collection.

Authorizations:
path Parameters
collection_id
required
string

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

query Parameters
update_mask
string

The list of fields to be updated, separated by a comma, e.g. field1,field2.

Each field should be in snake case, e.g. display_name.

For each field that you want to update, provide a corresponding value in the collection object containing the new value.

Request Body schema: application/json

Details of the collection to update.

display_name
required
string

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

authorized_query_domains
Array of strings

The list of authorized query domains for the collection.

Client-side / browser requests to the QueryCollection call can be made by any authorized query domain or any of its subdomains. This allows your interface to make search requests without having to provide an API key in the client-side request.

Responses

200

A successful response.

401

Returned when the request does not have valid authentication credentials.

403

Returned when the user does not have permission to access the resource.

404

Returned when the collection was not found.

500

Returned when the API encounters an internal error.

default

An unexpected error response

patch/v4/collections/{collection_id}
https://api-gateway.sajari.com/v4/collections/{collection_id}

Request samples

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": "string",
  • "account_id": "string",
  • "create_time": "2021-01-05T05:33:18Z",
  • "display_name": "string",
  • "authorized_query_domains":
    [
    ]
}

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 (QueryCollectionRequestPipeline)

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 (QueryCollectionRequestTracking)

Responses

200

A successful response.

401

Returned when the request does not have valid authentication credentials.

403

Returned when the user does not have permission to access the resource.

404

Returned when the resource does not exist.

500

Returned when the API encounters an internal error.

default

An unexpected error response

post/v4/collections/{collection_id}:queryCollection
https://api-gateway.sajari.com/v4/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": { },
  • "results":
    [
    ],
  • "total_size": "string",
  • "processing_duration": "string",
  • "aggregates":
    {