Search.io API (v4)

Download OpenAPI specification:Download

Search.io offers a search and discovery service with Neuralsearch®, the world's first instant AI search technology. Businesses of all sizes use Search.io to build site search and discovery solutions that maximize e-commerce revenue, optimize on-site customer experience, and scale their online presence.

Authentication

BasicAuth

The Search.io 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.search.io -u <key_id>:<key_secret>

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

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

For customers in Australia and New Zealand, use the https://au-api.search.io endpoint for faster routing to collections based in the au region.

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 an 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.

view
string
Default: "VIEW_UNSPECIFIED"
Enum: "VIEW_UNSPECIFIED" "BASIC" "FULL"

The amount of information to include in each retrieved collection.

  • VIEW_UNSPECIFIED: The default / unset value. The API defaults to the BASIC view.
  • BASIC: Include basic information including display name and domains. This is the default value (for both ListCollections and GetCollection).
  • FULL: Include the information from BASIC, plus full collection details like disk usage.
header Parameters
Account-Id
string

The account that owns this set of collections, e.g. 1618535966441231024.

Responses

Response samples

Content type
application/json
{
  • "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 Search.io 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\-]*$.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Request Body schema: application/json

Details of the collection to create.

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.

display_name
required
string

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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "account_id": "string",
  • "authorized_query_domains": [
    ],
  • "create_time": "2019-08-24T14:15:22Z",
  • "display_name": "string",
  • "id": "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.

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Responses

Response samples

Content type
application/json
null

Get collection

Retrieve the details of a collection.

Authorizations:
path Parameters
collection_id
required
string

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

query Parameters
view
string
Default: "VIEW_UNSPECIFIED"
Enum: "VIEW_UNSPECIFIED" "BASIC" "FULL"

The amount of information to include in the retrieved pipeline.

  • VIEW_UNSPECIFIED: The default / unset value. The API defaults to the BASIC view.
  • BASIC: Include basic information including display name and domains. This is the default value (for both ListCollections and GetCollection).
  • FULL: Include the information from BASIC, plus full collection details like disk usage.
header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Responses

Response samples

Content type
application/json
{
  • "account_id": "string",
  • "authorized_query_domains": [
    ],
  • "create_time": "2019-08-24T14:15:22Z",
  • "display_name": "string",
  • "id": "string"
}

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 update, separated by a comma, e.g. authorized_query_domains,display_name.

Each field should be in snake case.

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

header Parameters
Account-Id
string

The account that owns the collection, e.g. 1618535966441231024.

Request Body schema: application/json

The details of the collection to update.

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.

display_name
required
string

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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "account_id": "string",
  • "authorized_query_domains": [
    ],
  • "create_time": "2019-08-24T14:15:22Z",
  • "display_name": "string",
  • "id": "string"
}

Experiment

Run a query on a collection with a hypothetical configuration to see what kinds of results it produces.

Saved promotions with a start date in the future are enabled during the experiment, unless they are explicitly disabled.

The following example demonstrates how to run a simple experiment for a string, against a pipeline and with a proposed promotion:

{
  "pipeline": { "name": "my-pipeline" },
  "variables": { "q": "search terms" },
  "promotions": [{
    "id": "1234",
    "condition": "q = 'search terms'",
    "pins": [{
      "key": { "field": "id", "value": "54hdc7h2334h" },
      "position": 1
    }]
  }]
}
Authorizations:
path Parameters
collection_id
required
string

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

Request Body schema: application/json
object (Pipeline)
object (ExperimentRequestPipeline)

The pipeline to use when running the experiment.

If not provided the default query pipeline is used.

Array of objects (Promotion) [ items ]

The promotions to consider active when running the search.

Provided promotions override existing promotions with the same ID.

required
object

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

The most important variable is q which is the query the user entered, for example:

{ "q": "search terms" }

To paginate through results, set the variables page and resultsPerPage, for example:

{ "q": "search terms", "page": 5, "resultsPerPage": 20 }

To sort results, set the variable sort to the name of one of your collection's schema fields, for example:

{ "q": "search terms", "sort": "name" }

To sort in reverse, prefix the schema field with a minus sign -, for example:

{ "q": "search terms", "sort": "-name" }

Responses

Request samples

Content type
application/json
{
  • "custom_pipeline": {
    },
  • "pipeline": {
    },
  • "promotions": [
    ],
  • "variables": {
    }
}

Response samples

Content type
application/json
{
  • "query_response": {